From 94d76acd79d3159f539da32b7cb0273eb2922b5d Mon Sep 17 00:00:00 2001 From: Mike Nitsenko Date: Tue, 1 Sep 2026 18:13:32 +0500 Subject: [PATCH] docs: explain editable SAML audience (CUB-2546) (#11706) * docs: explain editable SAML audience (CUB-2546) * docs: address SAML audience review feedback --- docs-mintlify/admin/sso/google-workspace.mdx | 70 +++++++++---------- docs-mintlify/admin/sso/index.mdx | 34 +++++++-- .../admin/sso/microsoft-entra-id/saml.mdx | 22 ++++-- docs-mintlify/admin/sso/okta/saml.mdx | 17 ++++- 4 files changed, 95 insertions(+), 48 deletions(-) diff --git a/docs-mintlify/admin/sso/google-workspace.mdx b/docs-mintlify/admin/sso/google-workspace.mdx index 696bcf7f76b11..75c407d074e60 100644 --- a/docs-mintlify/admin/sso/google-workspace.mdx +++ b/docs-mintlify/admin/sso/google-workspace.mdx @@ -20,19 +20,14 @@ Available on [Enterprise plan](https://cube.dev/pricing). First, we'll enable SAML authentication in Cube Cloud. To do this, log in to Cube Cloud and -1. Click your username from the top-right corner, then click **Team & - Security**. +1. Navigate to **Admin → Settings**. +2. On the **Authentication & SSO** tab, enable **SAML**. +3. For a new integration, replace any prefilled **Audience (SP Entity ID)** + value with the **Single Sign-On URL** shown directly above it. -2. On the **Authentication & SSO** tab, ensure **SAML** is - enabled: - - - Cube Cloud Team Authentication and SSO tab - - -Take note of the **Single Sign On URL** and **Service Provider Entity -ID** values here, as we will need them in the next step when we configure -the SAML integration in Google Workspace. +Take note of the **Single Sign-On URL** and **Audience (SP Entity ID)** +values. You will need them when you configure the SAML integration in Google +Workspace. ## Create a SAML Integration in Google Workspace @@ -69,48 +64,53 @@ Workspace][google-docs-create-saml-app]. 5. Enter the following values for the **Service provider details** section and click **Continue**. -| Name | Description | -| --------- | ------------------------------------------------------------------- | -| ACS URL | Use the **Single Sign On URL** value from Cube Cloud | -| Entity ID | Use the **Service Provider Entity ID** value from Cube Cloud | +| Name | Description | +| --------- | ----------- | +| ACS URL | Use the **Single Sign-On URL** value from Cube Cloud. | +| Entity ID | Use the **Audience (SP Entity ID)** value from Cube Cloud. | -5. On the final screen, click **Finish**. +6. On the final screen, click **Finish**. -6. From the app details page, click **User access** and ensure the app is +7. From the app details page, click **User access** and ensure the app is **ON for everyone**: -## Enable SAML in Cube Cloud +## Complete SAML configuration in Cube Cloud In this step, we'll finalise the configuration by entering the values from our SAML integration in Google into Cube Cloud. -1. From the same **Authentication & SSO > SAML** tab, click the - **Advanced Settings** tab: - - - - - -2. Enter the following values in the **SAML Settings** section: +1. Return to **Admin → Settings → Authentication & SSO → SAML**. +2. Confirm that **Audience (SP Entity ID)** still matches the **Single + Sign-On URL** exactly. +3. Enter the following values in the **SAML Settings** section: -| Name | Description | -| --------------------------- | ------------------------------------------------------------------ | -| Audience (SP Entity ID) | Delete the prefilled value and leave empty | -| IdP Issuer (IdP Entity ID) | Use the **Issuer** value from Google Workspace | -| Identity Provider Login URL | Use the **Sign on URL** value from Google Workspace | -| Certificate | Use the **Signing Certificate** value from Google Workspace | +| Name | Description | +| --- | --- | +| Entity ID / Issuer | Use the **Entity ID** value from Google Workspace. | +| SSO (Sign on) URL | Use the **SSO URL** value from Google Workspace. | +| Certificate | Use the **Certificate** value from Google Workspace. | -3. Enable **Auto-provision new users** if you want users to be automatically +4. Enable **Auto-provision new users** if you want users to be automatically created in Cube on their first login via this SAML provider. New users are assigned the Viewer role by default — see [Default role for new users](#default-role-for-new-users) to choose a different role. Enable this if you are not using SCIM provisioning. -4. Scroll down and click **Save SAML Settings** to save the changes. +5. Click **Apply** to save the changes. + + + +Existing working Google Workspace integrations with a blank Audience do not +need to change immediately. A blank Audience disables audience validation. To +enable validation, update the Google **Entity ID** and Cube **Audience (SP +Entity ID)** together, keep another authentication method enabled, and test +SAML sign-in before you disable the fallback method. + + ## Default role for new users diff --git a/docs-mintlify/admin/sso/index.mdx b/docs-mintlify/admin/sso/index.mdx index 74e1c8065a856..cf8e1b326a6c0 100644 --- a/docs-mintlify/admin/sso/index.mdx +++ b/docs-mintlify/admin/sso/index.mdx @@ -18,10 +18,6 @@ Cube Cloud also provides single sign-on (SSO) via identity providers supporting - - - - ## Configuration To manage authentication settings, navigate to **Admin → Settings** @@ -47,8 +43,36 @@ Check the following guides to get tool-specific instructions on configuration: +#### Match SAML service provider identifiers + +Cube shows two service provider values in the SAML settings: + +| Cube setting | Identity provider setting | +| --- | --- | +| **Single Sign-On URL** | ACS URL or Reply URL | +| **Audience (SP Entity ID)** | Audience, Entity ID, or SP Entity ID | + +The **Audience (SP Entity ID)** value validates the audience in SAML responses. +It must exactly match the value configured in your identity provider. Leaving +the field blank disables audience validation and is supported only for +compatibility with existing configurations. + +Some identity providers, including Amazon Federate, use one service provider +identifier for both the AuthnRequest issuer and the response audience. For +these providers, set **Audience (SP Entity ID)** in Cube to the **Single +Sign-On URL**, then use that same value as the identity provider's Entity ID +or Audience. + + + +Existing working SAML integrations do not need to change their Audience. When +you change an existing configuration, keep another authentication method +enabled until you have tested SAML sign-in in a separate browser session. + + + [wiki-saml]: https://en.wikipedia.org/wiki/SAML_2.0 [ref-apis]: /reference [ref-dap]: /docs/data-modeling/data-access-policies [ref-security-context]: /docs/data-modeling/access-control/context -[ref-auth-integration]: /docs/data-modeling/access-control#authentication-integration \ No newline at end of file +[ref-auth-integration]: /docs/data-modeling/access-control#authentication-integration diff --git a/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx b/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx index ce1bdc5a333d2..931f8cf99f751 100644 --- a/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx +++ b/docs-mintlify/admin/sso/microsoft-entra-id/saml.mdx @@ -29,9 +29,19 @@ First, enable SAML authentication in Cube: 1. In Cube, navigate to **Admin → Settings**. 2. On the **Authentication & SSO** tab, enable the **SAML** toggle. -3. Take note of the **Single Sign-On URL** and **Audience** - values — you'll need them when configuring the Enterprise Application - in Entra. +3. For a new integration, set **Audience (SP Entity ID)** to the + **Single Sign-On URL** shown directly above it. +4. Take note of the **Single Sign-On URL** and **Audience (SP Entity ID)** + values — you'll need them when configuring the Enterprise Application in + Entra. + + + +Existing working Entra integrations with a different Audience do not need to +change. Keep the existing audience claim override unless you intentionally +update both sides of the integration. + + ## Create an Enterprise Application in Entra @@ -49,8 +59,10 @@ First, enable SAML authentication in Cube: 2. In the **Basic SAML Configuration** section, enter the following: - **Entity ID** — Use the **Single Sign-On URL** value from Cube. - **Reply URL** — Use the **Single Sign-On URL** value from Cube. -3. Go to **Attributes & Claims → Edit → Advanced settings** and - set the audience claim override to the **Audience** value from Cube. +3. If the **Audience (SP Entity ID)** value from Cube differs from the + **Entity ID** configured in the previous step, go to **Attributes & Claims + → Edit → Advanced settings** and set the audience claim override to the + Cube value. If the values match, no audience claim override is required. 4. Go to **SAML Certificates → Edit** and select **Sign SAML response and assertion** for the **Signing Option**. 5. Download the **Federation Metadata XML** file — you'll need it diff --git a/docs-mintlify/admin/sso/okta/saml.mdx b/docs-mintlify/admin/sso/okta/saml.mdx index 41b384dab1b77..b7dffe741b708 100644 --- a/docs-mintlify/admin/sso/okta/saml.mdx +++ b/docs-mintlify/admin/sso/okta/saml.mdx @@ -29,9 +29,20 @@ First, enable SAML authentication in Cube Cloud: 1. In Cube Cloud, navigate to **Admin → Settings**. 2. On the **Authentication & SSO** tab, enable the **SAML** toggle. -3. Take note of the **Single Sign-On URL** and **Audience** +3. For a new integration, set **Audience (SP Entity ID)** to the + **Single Sign-On URL** shown directly above it. This gives the AuthnRequest + issuer and response audience one matching service provider identifier. +4. Take note of the **Single Sign-On URL** and **Audience (SP Entity ID)** values — you'll need them when configuring the SAML integration in Okta. + + +Existing working Okta integrations with a different Audience do not need to +change. If you update the value, change it in Cube and Okta together and test +SAML sign-in before disabling another authentication method. + + + ## Create a SAML integration in Okta 1. Log in to your Okta organization as an administrator, then navigate to @@ -43,8 +54,8 @@ First, enable SAML authentication in Cube Cloud: 5. Enter the following values in the **SAML Settings** section: - **Single sign on URL** — Use the **Single Sign-On URL** value from Cube Cloud. - - **Audience URI (SP Entity ID)** — Use the **Audience** - value from Cube Cloud. + - **Audience URI (SP Entity ID)** — Use the **Audience (SP Entity ID)** + value from Cube Cloud. It must match exactly. 6. Click **Next** to go to the **Feedback** screen, fill in any necessary details and click **Finish**.