The two group models
Stacklok Enterprise has two things called groups, and they are not the same thing. They are maintained separately, matched differently, and the platform does not keep them in sync. Knowing which one a given control uses is the difference between a policy that works and one that silently does nothing.
Directory groups
A directory group is a record in the directory service, with its own identifier, a name, and an explicit membership list. You see and edit them in the console under User management, and they can be provisioned from your identity provider over SCIM or created directly through the API.
Directory groups decide connector access. When a developer's MCP client asks what tools it can reach, the MCP gateway resolves the caller to a directory user, reads that user's directory group memberships, and exposes only the connectors granted to those groups. Adding someone to a group in the console changes what their client can see.
They also carry budgets. A group budget is addressed by the directory group's identifier.
OIDC claim groups
An OIDC claim group is just a string that appears in the groups claim of the caller's token. It has no record anywhere in the platform; it exists only as text inside a token your identity provider issued.
Claim groups decide cluster-level authorization. The PlatformRoleBinding,
ClusterPlatformRoleBinding, and ToolhiveAuthorizationPolicy resources name
groups as plain strings, and those strings are matched against the token's
claim. Nothing on that path consults the directory.
Why this matters
Because the two are independent, all of the following are true at once:
- Adding a user to a directory group in the console does change their
connector access, and does not change what any
PlatformRoleBindinggrants them. - Adding a user to a group in your identity provider does change what claim groups their next token carries, and does not create directory membership unless SCIM is provisioning groups.
- Two groups with the same name in both systems are a coincidence you are maintaining, not a link the platform enforces.
The failure this produces is quiet. Someone adds a colleague to the Engineering group in the console, the colleague still cannot call a tool governed by a cluster authorization policy, and nothing anywhere reports an error, because both systems behaved exactly as configured.
Which one am I using?
| If you are configuring | You are naming |
|---|---|
| Connector access in the console or the directory API | A directory group |
| A group budget | A directory group |
PlatformRoleBinding or ClusterPlatformRoleBinding | An OIDC claim group |
ToolhiveAuthorizationPolicy | An OIDC claim group |
Keeping them aligned
If you want one set of groups to govern both, provision directory groups from the same identity provider groups you name in authorization policy, and keep the names identical. SCIM group provisioning is what makes that maintainable, because membership then tracks your provider on both sides.
That alignment is a convention you choose and maintain. The platform will not warn you when the two drift.
Related information
- Users and groups for directory group administration.
- SCIM provisioning to source directory groups from your identity provider.
- Enterprise authorization for the cluster-level policy that matches claim groups.