SSO Group Role Mapping

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.

SSO group role mapping is available on Dedicated Cloud and Self-Hosted deployments. On Multi-Tenant SaaS, 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:

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.

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.

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.

{
  "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.

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.

HoneyHive reads the configured claim and parses each group. Malformed groups and groups without a HoneyHive prefix are skipped.
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).
Each declaration is resolved against the current scope tree. Unknown or archived scope slugs are skipped.
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.

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 for the permission reference.

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.

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.

Emit the groups

Configure your IdP to put the group names in the ID token claim named by sso_group_field.

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.

Getting Started

Observability

Evaluation

Prompt Management

Administration

Learn More

Enable group mapping

Group claim requirements

Group naming grammar

entitlement-roles-2026-8

Organization membership comes from email domain

entitlement-roles-2025-12

Customize role assignment

Troubleshooting

​Enable group mapping

​Group claim requirements

​Group naming grammar

​entitlement-roles-2026-8

​Organization membership comes from email domain

​What happens on sign-in

​entitlement-roles-2025-12

​Customize role assignment

​Troubleshooting

Enable group mapping

Group claim requirements

Group naming grammar

entitlement-roles-2026-8

Organization membership comes from email domain

What happens on sign-in

entitlement-roles-2025-12

Customize role assignment

Troubleshooting