Skip to main content

Directory groups and OIDC claim groups

Stacklok Enterprise uses directory groups for budgets and structured connector policies. It uses OpenID Connect (OIDC) claim groups for cluster authorization policy. Cedar-mode connector policies can match directory groups, token claims, or both. Choose the group model that matches the control you are configuring.

ControlGroup model
Connector access, structured policyDirectory group
Connector access, Cedar policyDirectory group or token claim
AI Gateway budgetDirectory group
PlatformRoleBinding or ClusterPlatformRoleBindingOIDC claim group
ToolhiveAuthorizationPolicyOIDC claim group

Directory groups​

A directory group is a record in the directory service with an identifier, name, and membership list. Administrators can manage directory groups in the console or provision them from an identity provider through System for Cross-domain Identity Management (SCIM).

The Connector Gateway resolves each caller to a directory user, and the directory evaluates each connector's policy against that user. A structured-mode policy grants access to directory groups. A Cedar-mode policy can match directory group (UserGroup) membership, claims from the caller's token such as principal.claim_department, or both. See Grant and revoke connector access to manage group grants in the console. AI Gateway group budgets also reference the directory group's identifier.

Cedar-mode policies are API-only

The console edits structured-mode grants only. To switch a connector to Cedar mode or write its Cedar document, use the connector policy routes of the Enterprise Manager API. For a Cedar-mode connector, the console shows a notice and disables group editing.

OIDC claim groups​

An OIDC claim group is a string in the caller's token. The PlatformRoleBinding, ClusterPlatformRoleBinding, and ToolhiveAuthorizationPolicy resources match these strings when evaluating cluster authorization policy.

These resources read group values directly from the token. Configure the identity provider to include the expected values.

Keeping them aligned​

To use the same organizational groups for both control planes, provision directory groups through SCIM from the identity provider that issues the OIDC group claims. Keep the directory group names and claim values aligned. Stacklok Enterprise evaluates the two group models independently.