From bfd4c07e17761558501d29f20f58c3eb377284b7 Mon Sep 17 00:00:00 2001 From: Artyom Keydunov Date: Fri, 22 May 2026 14:59:51 -0700 Subject: [PATCH 1/2] docs(sso): simplify "Map roles by group" sections Trims the SAML SSO and SCIM "Map roles by group" sections on the Okta and Microsoft Entra ID pages: clarifies that for SAML SSO, group mappings are evaluated only when a new user is auto-provisioned (not on every login), drops the internal `groupsRolesMap` setting name from docs, removes the legacy `rolesMap` callout, and removes a duplicate Admin Info block on the Entra SAML page. Co-authored-by: Cursor --- .../admin/sso/microsoft-entra-id/saml.mdx | 45 ++++--------------- .../admin/sso/microsoft-entra-id/scim.mdx | 23 ++++------ docs-mintlify/admin/sso/okta/saml.mdx | 36 ++++----------- docs-mintlify/admin/sso/okta/scim.mdx | 23 ++++------ 4 files changed, 34 insertions(+), 93 deletions(-) diff --git a/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx b/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx index 9a1e19da4efa9..f584f5bbc553e 100644 --- a/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx +++ b/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx @@ -136,9 +136,7 @@ the **Viewer** role by default. To assign a different role, expand the The selected role applies **only when a user is first created** during provisioning. Existing users are not modified on subsequent SSO logins or -SCIM updates. It is applied **in addition to** any roles your identity -provider sends via the [role attribute](#configure-attribute-mappings) -(subject to the `rolesMap`). +SCIM updates. @@ -158,13 +156,6 @@ exists. - - -Admin status cannot be set via SSO. To grant admin permissions, update -the user's role manually in Cube under **Team & Security**. - - - ## Map roles by group For finer-grained role assignment, enable **Map roles by group** in the @@ -192,33 +183,15 @@ To configure group-based role mapping: 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. +For SAML SSO, group mappings are evaluated **only when a new user is +auto-provisioned** on first login. Each matching group adds its mapped +role to the new user, on top of the +[default role](#default-role-for-new-users). Existing users are not +modified on subsequent logins. -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. - - - -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. - - +The same mapping is also applied by [SCIM][ref-scim] when group +memberships are pushed, so a single configuration drives both SAML SSO +and SCIM group sync. ## Assign users diff --git a/docs-mintlify/admin/sso/microsoft-entra-id/scim.mdx b/docs-mintlify/admin/sso/microsoft-entra-id/scim.mdx index 15a1687c6fea3..04d178bd3edb5 100644 --- a/docs-mintlify/admin/sso/microsoft-entra-id/scim.mdx +++ b/docs-mintlify/admin/sso/microsoft-entra-id/scim.mdx @@ -87,23 +87,16 @@ Users**. ## 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. +on the SAML setup page, the same mapping is applied when SCIM provisions +group memberships from Entra — when Entra adds a user to a synchronized +group, Cube assigns the mapped role to that user. Role assignment is +**additive**: removing a user from an Entra group does not strip the +corresponding role; adjust the user's roles in Cube manually. 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. +mapping is defined on the SAML page, it drives both SAML SSO and SCIM +group sync. Match is on the group **display name** Entra pushes (the +`displayName` attribute in the **Group** mapping, case-insensitive). ## Syncing user attributes diff --git a/docs-mintlify/admin/sso/okta/saml.mdx b/docs-mintlify/admin/sso/okta/saml.mdx index 79272d06da131..a21ba900ffc0c 100644 --- a/docs-mintlify/admin/sso/okta/saml.mdx +++ b/docs-mintlify/admin/sso/okta/saml.mdx @@ -119,8 +119,7 @@ the **Viewer** role by default. To assign a different role, expand the The selected role applies **only when a user is first created** during provisioning. Existing users are not modified on subsequent SSO logins or -SCIM updates. It is applied **in addition to** any roles your identity -provider sends via the role attribute (subject to the `rolesMap`). +SCIM updates. @@ -163,32 +162,15 @@ To configure group-based role mapping: appears in the SAML assertion (case-insensitive). - **Cube Cloud role** — pick a default or [custom role][ref-custom-roles]. -How it's applied: +For SAML SSO, group mappings are evaluated **only when a new user is +auto-provisioned** on first login. Each matching group adds its mapped +role to the new user, on top of the +[default role](#default-role-for-new-users). Existing users are not +modified on subsequent logins. -- 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. - - - -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. - - +The same mapping is also applied by [SCIM][ref-scim] when group +memberships are pushed, so a single configuration drives both SAML SSO +and SCIM group sync. ## Test SAML authentication diff --git a/docs-mintlify/admin/sso/okta/scim.mdx b/docs-mintlify/admin/sso/okta/scim.mdx index 0434affac0ece..d71feac96f2c9 100644 --- a/docs-mintlify/admin/sso/okta/scim.mdx +++ b/docs-mintlify/admin/sso/okta/scim.mdx @@ -134,23 +134,16 @@ 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. +on the SAML setup page, the same mapping is applied when SCIM pushes +group memberships from Okta — when Okta adds a user to a pushed group, +Cube Cloud assigns the mapped role to that user. Role assignment is +**additive**: removing a user from an Okta group does not strip the +corresponding role; adjust the user's roles in Cube Cloud manually. 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. +mapping is defined on the SAML page, it drives both SAML SSO and SCIM +group sync. Match is on the group **display name** Okta pushes +(case-insensitive). [ref-saml]: /admin/sso/okta/saml [ref-saml-default-role]: /admin/sso/okta/saml#default-role-for-new-users From 520394bbbe12ce83627913c7e4691d15fc1fea08 Mon Sep 17 00:00:00 2001 From: Artyom Keydunov Date: Fri, 22 May 2026 15:00:35 -0700 Subject: [PATCH 2/2] docs(sso): correct SAML SSO group-mapping semantics Group-mapped roles replace the default role for newly auto-provisioned users (instead of stacking on top of it). The default role is used only as a fallback when no IdP group matches or the mapped roles no longer exist. Co-authored-by: Cursor --- docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx | 10 ++++++---- docs-mintlify/admin/sso/okta/saml.mdx | 10 ++++++---- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx b/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx index f584f5bbc553e..ce1bdc5a333d2 100644 --- a/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx +++ b/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx @@ -184,10 +184,12 @@ To configure group-based role mapping: - **Cube role** — pick a default or [custom role][ref-custom-roles]. For SAML SSO, group mappings are evaluated **only when a new user is -auto-provisioned** on first login. Each matching group adds its mapped -role to the new user, on top of the -[default role](#default-role-for-new-users). Existing users are not -modified on subsequent logins. +auto-provisioned** on first login. If any matching group resolves to a +Cube role, those roles are assigned to the new user **instead of** the +configured [default role](#default-role-for-new-users). The default role +is used as a fallback when no IdP group matches (or when the mapped Cube +roles no longer exist). Existing users' role assignments are never +modified by subsequent logins. The same mapping is also applied by [SCIM][ref-scim] when group memberships are pushed, so a single configuration drives both SAML SSO diff --git a/docs-mintlify/admin/sso/okta/saml.mdx b/docs-mintlify/admin/sso/okta/saml.mdx index a21ba900ffc0c..41b384dab1b77 100644 --- a/docs-mintlify/admin/sso/okta/saml.mdx +++ b/docs-mintlify/admin/sso/okta/saml.mdx @@ -163,10 +163,12 @@ To configure group-based role mapping: - **Cube Cloud role** — pick a default or [custom role][ref-custom-roles]. For SAML SSO, group mappings are evaluated **only when a new user is -auto-provisioned** on first login. Each matching group adds its mapped -role to the new user, on top of the -[default role](#default-role-for-new-users). Existing users are not -modified on subsequent logins. +auto-provisioned** on first login. If any matching group resolves to a +Cube Cloud role, those roles are assigned to the new user **instead of** +the configured [default role](#default-role-for-new-users). The default +role is used as a fallback when no IdP group matches (or when the mapped +Cube Cloud roles no longer exist). Existing users' role assignments are +never modified by subsequent logins. The same mapping is also applied by [SCIM][ref-scim] when group memberships are pushed, so a single configuration drives both SAML SSO