> ## Documentation Index > Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt > Use this file to discover all available pages before exploring further. # SSO Group Role Mapping > Assign HoneyHive roles and memberships from identity provider group claims, including claim requirements, the group naming grammar, and how to customize role assignment. HoneyHive can derive a user's roles, and optionally their data plane, workspace, and project memberships, from group names your identity provider (IdP) sends in the ID token. You control access by adding people to groups in your IdP. HoneyHive rebuilds the user's access from their current groups on every sign-in. > [!NOTE] > > SSO group role mapping is available on [Dedicated Cloud](https://docs.honeyhive.ai/v2/setup/dedicated.md) and [Self-Hosted](https://docs.honeyhive.ai/v2/setup/self-hosted.md) deployments. On [Multi-Tenant SaaS](https://docs.honeyhive.ai/v2/setup/managed.md), roles are assigned in HoneyHive. ## Enable group mapping Group mapping is set in the control-plane license policy. On Dedicated Cloud, HoneyHive sets these values for you. On Self-Hosted, set them in the control-plane chart's values: ```yaml theme={null} license: license_policy: sso_group_scheme: "entitlement-roles-2026-8" # or entitlement-roles-2025-12 sso_group_field: "groups" # optional, defaults to group_list ``` After changing either value, roll out the control-plane backend so it reloads the license. > [!NOTE] > > The default roles manifests listed below are the Self-Hosted defaults. Dedicated Cloud organizations start from a different default manifest under either scheme, with `OrgAdmin`, `OrgMember`, `DataPlaneAdmin`, `DataPlaneMember`, `WorkspaceAdmin`, `WorkspaceMember`, `ProjectAdmin`, and `ProjectMember`. Always name groups after the roles in your organization's own manifest. | Setting | Values | Effect | | - | - | - | | `sso_group_scheme` | `entitlement-roles-2026-8` | Roles **and** data plane, workspace, and project memberships come from groups. Recommended for new deployments. | | | `entitlement-roles-2025-12` | Roles and data plane memberships come from groups. Workspace and project memberships are managed in HoneyHive. | | | unset | Group claims are ignored. Access is managed in HoneyHive. | | `sso_group_field` | Any claim name up to 200 characters | The ID token claim HoneyHive reads groups from. | > [!WARNING] > > With a scheme enabled, every user who signs in must carry at least one valid HoneyHive group, or sign-in fails. Enable it only once your IdP sends groups for all HoneyHive users. ## Group claim requirements * **Location:** a top-level claim in the **ID token**. Groups in the access token or userinfo response are not read. * **Claim name:** the exact value of `sso_group_field`, matched literally. `https://example.com/groups` is read as one key, not as a nested path. The name is not trimmed, so avoid leading or trailing spaces. * **Value type:** a string (one group) or an array of strings. Any other type, such as an object or a number, fails sign-in. There is no limit on the number of groups. * **Content:** group **names**, not IdP object IDs. Some IdPs emit group object IDs by default; configure yours to emit names. * **Filtering:** groups without a HoneyHive prefix are ignored, so you can send a user's full group list. To keep tokens small, filter the claim to HoneyHive groups in your IdP. ```json theme={null} { "sub": "samlp|acme-saml|E12345", "email": "alice@acme.com", "group_list": [ "SGG-HoneyHive-Acme-OrgAdmin", "SGG-HoneyHive-ChatAgent-Admin", "Finance-Team" ] } ``` ## Group naming grammar Every HoneyHive group has exactly four hyphen-separated segments: ``` {prefix}-{product}-{scope_name}-{role_name} ``` | Segment | Rule | | - | - | | `{prefix}-{product}` | One of `SGG-HoneyHive`, `SGG-HH`, or `SGG-HoneyHiveProd` (all equivalent). `entitlement-roles-2026-8` also accepts `SGG-GenAI_PaaS`. | | `{scope_name}` | The **slug** of the organization, data plane, or workspace, matched exactly and case-sensitively. Use letters, digits, and underscores. `entitlement-roles-2025-12` also accepts a project slug. `ControlPlane` targets the control plane. | | `{role_name}` | The exact name of a role defined in your organization's roles manifest, for example `OrgAdmin` or `Admin`. Case-sensitive. | Because the grammar splits on `-`, a hyphen anywhere in the scope slug or role name produces the wrong number of segments and the group is ignored. Use underscores instead (`Chat_Agent`, not `Chat-Agent`). `SGG-HoneyHive-System-Bootstrap` is a special group equivalent to `SGG-HoneyHive-ControlPlane-ControlPlaneAdmin`. It grants control plane administration for initial deployment setup. Use the `SGG-HoneyHive`, `SGG-HH`, or `SGG-HoneyHiveProd` prefix for this group. `SGG-GenAI_PaaS-System-Bootstrap` is not recognized and grants nothing. > [!NOTE] > > HoneyHive does not validate `{role_name}` against your roles manifest. A group naming a role that does not exist is accepted but grants no permissions. Check spelling against **Settings > Organization > Roles**. ## entitlement-roles-2026-8 Each group declares a role on one scope. Declarations are explicit, with no wildcards. | Declared scope | What the user gets | | - | - | | Control plane | The role (for example `ControlPlaneAdmin`) on the control plane. | | Organization | The role on the organization. The user must already be an organization member (see below). | | Data plane | Membership in the data plane only. Its workspaces are not exposed. The default manifest defines no data plane role, so the `{role_name}` segment is a placeholder that grants nothing on its own (for example `SGG-HoneyHive-Banking-Member`). Data plane permissions cascade from the user's organization role. You rarely need this group, because a workspace declaration already implies its data plane. | | Workspace | Membership and the role in the workspace, plus membership in its parent data plane and in every project in the workspace. | | Project | Not supported. Project access comes from the workspace declaration. | On Self-Hosted, the default roles manifest for this scheme defines: | Role | Scope | Typical group | | - | - | - | | `OrgAdmin` | Organization | `SGG-HoneyHive-Acme-OrgAdmin` | | `OrgMember` | Organization | Assigned automatically to every organization member, no group needed. | | `Admin` | Workspace | `SGG-HoneyHive-ChatAgent-Admin` | | `Member` | Workspace | `SGG-HoneyHive-ChatAgent-Member` | Workspace roles apply to the workspace's projects through the permissions defined on the role. Because memberships come from groups, the **Add member**, **Remove member**, and role assignment controls are disabled in HoneyHive at every scope, including the organization. There is no invite flow: users join the organization by email domain and everything else comes from groups. ### Organization membership comes from email domain Groups never create organization membership. A user joins an organization when their email domain matches one of the organization's **email domains** (set when the organization is created, or under organization settings). If a user declares a data plane or workspace in an organization they are not a member of, sign-in fails with an error naming the organization. An organization role group for an organization the user is not in is ignored. ### What happens on sign-in 1. HoneyHive reads the configured claim and parses each group. Malformed groups and groups without a HoneyHive prefix are skipped. 2. Data plane, workspace, and project roles and memberships are rebuilt from scratch. Control plane and organization memberships keep only their baseline roles (`User` and `OrgMember`). 3. Each declaration is resolved against the current scope tree. Unknown or archived scope slugs are skipped. 4. HoneyHive writes the resulting memberships, removing memberships no longer declared. Sign-in fails if a user has no groups, or if none of them is well formed. Groups that are well formed but name a scope that does not resolve do not fail sign-in. The user signs in without the access those groups would grant, which is the usual symptom of a misspelled slug. The whole update is atomic: if sign-in fails, the user's previous access is unchanged. **Removing a user from a group removes that access on their next sign-in.** HoneyHive rejects role and membership edits on SSO-managed scopes with an explanatory error, so change the group in your IdP instead. ## entitlement-roles-2025-12 This scheme assigns roles from groups but leaves workspace and project membership to HoneyHive invites. * Data plane memberships are synced from groups: a declared data plane is added and an undeclared one is removed. * Groups on a workspace or project only add the role if the user is already a member of that scope. * Assigning roles to members is disabled in HoneyHive. Adding and removing members stays enabled. * On Self-Hosted, the default roles manifest defines `OrgAdmin`, `DataPlaneAdmin`, `DataPlaneMember`, `WorkspaceAdmin`, `WorkspaceMember`, `ProjectAdmin`, and `ProjectMember`. It also supports wildcard suffixes on the scope slug: | Pattern | Applies the role to | | - | - | | `{dataplane}_WS` | Every workspace in the data plane that the user is a member of | | `{workspace}_PJ` | Every project in the workspace that the user is a member of | | `{dataplane}_WS_PJ` | Every project in every workspace of the data plane that the user is a member of (not the workspaces themselves) | For example, `SGG-HoneyHive-Banking_WS-WorkspaceAdmin` makes the user Workspace Admin in every workspace of the `Banking` data plane they belong to. In `entitlement-roles-2026-8`, `_WS` and `_PJ` are ordinary characters in a slug. ## Customize role assignment You decide what each group grants by combining two things you control: the roles manifest and your IdP groups. **1. Define roles** Go to **Settings > Organization > Roles** and edit the roles manifest. This defines what each role can do and stays available under every scheme. Custom role definitions require the Enterprise plan. Add or change roles and their permissions to match your access policy, for example a read-only `Viewer` role at workspace scope. See [Roles](https://docs.honeyhive.ai/v2/workspace/roles.md) for the permission reference. **2. Choose stable slugs** On `entitlement-roles-2026-8`, give each organization and workspace a slug when you create it. On `entitlement-roles-2025-12`, the create form derives the slug from the display name and appends a random suffix, so read the generated slug from the scope's card in the **Admin Center** and name your groups after it. The API also accepts a chosen workspace slug on either scheme. The slug is the stable identifier your groups reference. Changing a slug breaks every group that names it. **3. Create IdP groups** Create one IdP group per scope and role, named with the grammar above, for example `SGG-HoneyHive-ChatAgent-Viewer`. Role names must match the manifest exactly and must not contain hyphens. **4. Emit the groups** Configure your IdP to put the group names in the ID token claim named by `sso_group_field`. **5. Verify** Sign in as a test user in each group and confirm the expected workspaces and actions appear. Roles are recomputed on the next sign-in after any group change. A user in several groups receives all of the declared roles. Two groups that name the same scope merge into one membership with both roles. ## Troubleshooting | Symptom | Cause | | - | - | | Sign-in fails: "No SSO group claims found in the configured token field" | The claim named by `sso_group_field` is missing or empty in the ID token. | | Sign-in fails: "No valid declarations found in SSO token" | None of the user's groups has a HoneyHive prefix and exactly four segments. | | Sign-in fails: "The configured SSO group claim must be a string or an array of strings" | The claim holds an object, number, or mixed array. | | Sign-in fails: "No membership in org '...'" | The user declares a data plane or workspace in an organization whose email domains do not include the user's email domain. | | A group grants nothing | The slug is misspelled, differs in case, or names an archived scope; the role name is not in the manifest; or a hyphen splits the group into more than four segments. | | An `OrgAdmin` group does nothing | The user is not an organization member. Add their email domain to the organization. | | Role or membership edits in HoneyHive fail with "managed via SSO group membership" | The scheme manages these from groups. Change the group in your IdP instead. | ## Related topics - [Role Based Access Control](https://docs.honeyhive.ai/v2/workspace/roles.md) - [Enterprise SSO on Multi-Tenant SaaS](https://docs.honeyhive.ai/v2/workspace/enterprise-sso.md) - [Inviting Teammates](https://docs.honeyhive.ai/v2/workspace/inviting-teammates.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.