docs(sso): document SAML + SCIM "Map roles by group" (CUB-2653) (#10938)

keydunov · cursoragent · web-flow · commit 3748390339b2 · 2026-05-22T12:36:21.000-07:00
Adds Map roles by group sections to the Okta and Microsoft Entra ID
SAML pages and cross-links them from the matching SCIM pages, covering
the new groupsRolesMap setting, the attributeGroups SAML attribute, the
additive role-assignment semantics, and the IdP-side group claim setup
required for Okta. Notes that Entra's canonical groups claim URL is
read automatically.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx b/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx
@@ -72,6 +72,23 @@ Create explicit SAML claims in Entra with the names Cube uses by default.
    - **Display name** — Set **Name** to `name` and **Source attribute** to
      `user.displayname`.
 
+If you plan to map Cube roles based on Entra group membership (see
+[Map roles by group](#map-roles-by-group) below), also add a group claim:
+
+1. Still in **Attributes & Claims**, click **Add a group claim**.
+2. Choose which groups to include (e.g. **Security groups** or **Groups
+   assigned to the application**) and pick a **Source attribute** for the
+   group name. For most setups, select **sAMAccountName** or
+   **Cloud-only group display names** so the assertion carries
+   human-readable group names that match the **IdP group name** values
+   you'll configure in Cube Cloud.
+3. Save the claim.
+
+   Cube reads Entra's canonical groups claim URL
+   (`http://schemas.microsoft.com/ws/2008/06/identity/claims/groups`)
+   automatically, so no further attribute renaming is required on the
+   Entra side.
+
 ## Complete configuration in Cube
 
 Return to the SAML configuration page in Cube and provide the identity
@@ -148,6 +165,61 @@ the user's role manually in Cube under **Team & Security**.
 
 </Info>
 
+## Map roles by group
+
+For finer-grained role assignment, enable **Map roles by group** in the
+**Advanced Settings** section to assign Cube roles based on a user's
+Entra group memberships.
+
+To configure group-based role mapping:
+
+1. Make sure Entra sends a group claim on the SAML assertion. See the
+   group-claim step in [Configure attribute
+   mappings](#configure-attribute-mappings).
+2. In the SAML configuration form in Cube, expand **Advanced Settings**.
+3. (Optional) Under **SAML attribute customization**, set the **Groups
+   attribute** to the simple name of the SAML attribute carrying group
+   memberships. Defaults to `groups`. Cube also reads Entra's canonical
+   groups claim URL automatically, so the default usually works
+   out of the box.
+4. Enable the **Map roles by group** toggle.
+5. Click **Add group mapping** and create one entry per group you want
+   to map:
+   - **IdP group name** — the group display name as it appears in the
+     assertion (case-insensitive). With **Source attribute** set to
+     **sAMAccountName** or **Cloud-only group display names**, this is
+     the human-readable group name. If you left the default (group object
+     ID), use the GUID instead.
+   - **Cube role** — pick a default or [custom role][ref-custom-roles].
+
+How it's applied:
+
+- On every SAML SSO login, Cube reads the user's groups from the SAML
+  assertion and assigns the mapped role for each group that matches.
+- Group mapping is **additive**: roles are added on every login, but a
+  user is never demoted on subsequent logins (e.g. removing them from an
+  Entra group does not strip the corresponding Cube role — adjust the
+  user's roles in Cube manually).
+- Users whose groups don't match any entry still receive the
+  [default role](#default-role-for-new-users) on first login.
+- The **Default role for new users** picker continues to apply at
+  provisioning time as the always-on baseline.
+
+The same `groupsRolesMap` is also consumed by [SCIM][ref-scim] when
+groups are pushed and members are added, so a single configuration drives
+both SAML SSO and SCIM group sync.
+
+<Info>
+
+The legacy `rolesMap` setting (a translation from raw IdP role values to
+Cube role names, applied to the **Role attribute**) continues to work
+and is applied **in addition to** `groupsRolesMap`. They read different
+SAML attributes (`role` vs. `groups`) and can be used side by side —
+typical setups using Entra App Roles for the role attribute and Entra
+security groups for the group attribute.
+
+</Info>
+
 ## Assign users
 
 Make sure the new Enterprise Application is assigned to the relevant
diff --git a/docs-mintlify/admin/sso/microsoft-entra-id/scim.mdx b/docs-mintlify/admin/sso/microsoft-entra-id/scim.mdx
@@ -84,6 +84,27 @@ Users**.
 
 </Info>
 
+## Map roles by SCIM group
+
+If you have configured [Map roles by group][ref-saml-map-roles-by-group]
+on the SAML setup page, the same `groupsRolesMap` is applied whenever
+SCIM provisions group memberships from Entra:
+
+- When Entra adds a user to a synchronized group, Cube looks up the
+  group's **display name** (case-insensitive) in the configured mapping
+  and assigns the corresponding Cube role to that user.
+- Role assignment is **additive**: a user is never demoted on subsequent
+  group sync. Removing a user from an Entra group does not strip the
+  corresponding Cube role — adjust the user's roles in Cube manually.
+- The match is on the SCIM group **display name** that Entra pushes (the
+  `displayName` attribute in the **Group** mapping), not the group
+  object ID. Make sure the **IdP group name** entries in Cube match
+  exactly (case-insensitive) what Entra sends.
+
+No separate configuration is required on the SCIM side — once the
+mapping is defined on the SAML page, it drives both SAML SSO login and
+SCIM group sync.
+
 ## Syncing user attributes
 
 You can sync [user attributes][ref-user-attributes] from Microsoft Entra to
@@ -126,5 +147,6 @@ provisioned as [user attributes][ref-user-attributes] in Cube.
 
 [ref-saml]: /admin/sso/microsoft-entra-id/saml
 [ref-saml-default-role]: /admin/sso/microsoft-entra-id/saml#default-role-for-new-users
+[ref-saml-map-roles-by-group]: /admin/sso/microsoft-entra-id/saml#map-roles-by-group
 [ref-custom-roles]: /admin/users-and-permissions/custom-roles
 [ref-user-attributes]: /admin/users-and-permissions/user-attributes
diff --git a/docs-mintlify/admin/sso/okta/saml.mdx b/docs-mintlify/admin/sso/okta/saml.mdx
@@ -57,10 +57,24 @@ user attributes from Okta to Cube Cloud:
 2. Scroll down to the **Attribute statements** section.
 3. Click **Add expression** and create the following entries:
 
-| Name    | Expression                |
-| ------- | ------------------------- |
-| `email` | `user.profile.email`      |
-| `name`  | `user.profile.firstName`  |
+   | Name    | Expression                |
+   | ------- | ------------------------- |
+   | `email` | `user.profile.email`      |
+   | `name`  | `user.profile.firstName`  |
+
+4. If you plan to map Cube roles based on Okta group membership (see
+   [Map roles by group](#map-roles-by-group) below), also add a **Group
+   Attribute Statement**. Scroll to the **Group Attribute Statements**
+   section and add:
+
+   | Name     | Filter                |
+   | -------- | --------------------- |
+   | `groups` | **Matches regex** `.*` |
+
+   Adjust the filter to scope which groups Okta sends — e.g.
+   **Starts with** `cube-` to limit the assertion to Cube-related groups.
+   The attribute name must match the **Groups attribute** value configured
+   in Cube Cloud (defaults to `groups`).
 
 ## Retrieve SAML details from Okta
 
@@ -126,6 +140,56 @@ exists.
 
 </Warning>
 
+## Map roles by group
+
+For finer-grained role assignment, enable **Map roles by group** in the
+**Advanced Settings** section to assign Cube Cloud roles based on a user's
+Okta group memberships.
+
+To configure group-based role mapping:
+
+1. Make sure Okta sends a group attribute statement on the SAML assertion.
+   See step 4 of [Configure attribute statements in
+   Okta](#configure-attribute-statements-in-okta).
+2. In the SAML configuration form in Cube Cloud, expand **Advanced
+   Settings**.
+3. (Optional) Under **SAML attribute customization**, set the **Groups
+   attribute** to the name of the SAML attribute you configured in Okta.
+   Defaults to `groups`.
+4. Enable the **Map roles by group** toggle.
+5. Click **Add group mapping** and create one entry per group you want to
+   map:
+   - **IdP group name** — the Okta group **display name** exactly as it
+     appears in the SAML assertion (case-insensitive).
+   - **Cube Cloud role** — pick a default or [custom role][ref-custom-roles].
+
+How it's applied:
+
+- On every SAML SSO login, Cube Cloud reads the user's groups from the
+  configured **Groups attribute** and assigns the mapped role for each
+  group that matches.
+- Group mapping is **additive**: roles are added on every login, but a
+  user is never demoted on subsequent logins (e.g. removing them from an
+  Okta group does not strip the corresponding Cube role — adjust the
+  user's roles in Cube Cloud manually).
+- Users whose groups don't match any entry still receive the
+  [default role](#default-role-for-new-users) on first login.
+- The **Default role for new users** picker continues to apply at
+  provisioning time as the always-on baseline.
+
+The same `groupsRolesMap` is also consumed by [SCIM][ref-scim] when groups
+are pushed and members are added, so a single configuration drives both
+SAML SSO and SCIM group sync.
+
+<Info>
+
+The legacy `rolesMap` setting (a translation from raw IdP role values to
+Cube role names, applied to the **Role attribute**) continues to work
+and is applied **in addition to** `groupsRolesMap`. They read different
+SAML attributes (`role` vs. `groups`) and can be used side by side.
+
+</Info>
+
 ## Test SAML authentication
 
 1. Copy the **Single Sign-On URL** from the SAML configuration page
diff --git a/docs-mintlify/admin/sso/okta/scim.mdx b/docs-mintlify/admin/sso/okta/scim.mdx
@@ -129,8 +129,30 @@ this is the **Viewer** role; to choose a different default role (including
 
 The default role only applies to users created by SCIM (`POST
 /api/scim/v2/Users`). Existing users are not modified by subsequent SCIM
-profile or group updates.
+profile updates.
+
+## Map roles by SCIM group
+
+If you have configured [Map roles by group][ref-saml-map-roles-by-group]
+on the SAML setup page, the same `groupsRolesMap` is applied whenever
+SCIM pushes group memberships:
+
+- When Okta adds a user to a pushed group, Cube Cloud looks up the
+  group's **display name** (case-insensitive) in the configured mapping
+  and assigns the corresponding Cube Cloud role to that user.
+- Role assignment is **additive**: a user is never demoted on subsequent
+  group sync. Removing a user from an Okta group does not strip the
+  corresponding Cube Cloud role — adjust the user's roles in Cube Cloud
+  manually.
+- The match is on the **group display name** that Okta pushes via SCIM,
+  not the Okta group ID. Make sure the **IdP group name** entries in
+  Cube Cloud match exactly (case-insensitive) what Okta sends.
+
+No separate configuration is required on the SCIM side — once the
+mapping is defined on the SAML page, it drives both SAML SSO login and
+SCIM group sync.
 
 [ref-saml]: /admin/sso/okta/saml
 [ref-saml-default-role]: /admin/sso/okta/saml#default-role-for-new-users
+[ref-saml-map-roles-by-group]: /admin/sso/okta/saml#map-roles-by-group
 [ref-custom-roles]: /admin/users-and-permissions/custom-roles
