Groups

Overview of Groups within the Keycard platform.

A Group is a named collection of Users within a Zone. Groups let you grant access to a set of Users at once: assign a Role to a Group and every member inherits it, or name the Group in a policy instead of enumerating each User.

Groups are created and managed by an Admin. See Groups for the Console steps.

Source

A Group is either managed in Keycard or synced from an external directory over SCIM. A synced Group is owned by the directory: while directory sync is enabled for the Zone, its name and membership are read-only in Keycard and only the directory can delete it. Roles can still be assigned to it. See SCIM Provisioning.

Name and Identifier

Every Group has a display name and an identifier that is unique within the Zone. The identifier is what policy rules match on, so it is the stable reference for a Group. Both can be changed at any time, except the name of a synced Group, which follows the directory. Synced Groups get an identifier automatically.

Membership

A User can belong to any number of Groups. Groups cannot be nested: only Users can belong to Groups.

Roles

A Group can be assigned organization Roles and custom Zone Roles. Every member of the Group inherits them, and a User’s effective Roles are the union of the Roles assigned to them directly and the Roles assigned to every Group they belong to. Removing a User from a Group removes the Roles they were assigned through it.

Groups in Policy

Group membership is a first-class entity in policy evaluation. A Cedar rule matches a Group with the in operator:

permit (
  principal in Keycard::Group::"data-analysts",
  action,
  resource
);

See Group-based policies for the full policy reference and more examples.

Which kind of group to use

Three things look like “a set of people” to a policy rule. They resolve at different moments, and that decides how fast a change takes effect.

Mechanism	Resolved	A membership change takes effect	Use it for
Keycard Group, `principal in Keycard::Group::"data-analysts"`	When the request is evaluated	On the next request, with no new sign-in	Who someone is on your team: the data analysts, the on-call rotation. Manage it in Keycard or sync it over SCIM.
Identity provider `groups` claim, `context.subject_claims.groups`	At sign-in, from the ID token	At the User’s next sign-in; until then policy sees the old membership	Rules you already have that read the claim. Access Snowflake gates on it. Authenticate users with your identity provider says which providers can send it, and Send group claims covers the provider setup.
Role, `principal in Keycard::Role::"admin"`	When the request is evaluated	On the next request	What someone may administer: Admin or Viewer in the organization, Manager or Viewer on a custom Zone. Assign it to a User or to a Group.

The claim is the one with a gap. Remove someone from an Okta group and every session they already hold keeps the old membership until it ends, so a rule on the claim cannot cut access off mid-session. A Keycard Group has no such gap, and it also works for flows that run without a User session. Prefer Keycard Groups for new rules; the policy owner’s guidance on the claim is under Groups versus the IdP groups claim. Roles are the platform’s administrative Roles. Keycard::CustomRole is in the schema, but you can’t define your own Roles yet; see Role-based Policies.