> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SAML authentication with Okta

> Connects Okta to Cube Cloud with SAML so members authenticate through your existing Okta application.

With SAML (Security Assertion Markup Language) enabled, you can authenticate
users in Cube Cloud through Okta, allowing your team to access Cube Cloud
using single sign-on.

<Note>
  Available on [Enterprise plan](https://cube.dev/pricing).
</Note>

## Prerequisites

Before proceeding, ensure you have the following:

* Admin permissions in Cube Cloud.
* Account administrator permissions in your Okta organization to access
  the Admin Console and create SAML integrations.

## Enable SAML in Cube Cloud

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**
   values — you'll need them when configuring the SAML integration in Okta.

## Create a SAML integration in Okta

1. Log in to your Okta organization as an administrator, then navigate to
   the Admin Console by clicking **Admin** in the top-right corner.
2. Click **Applications → Applications** from the navigation on the
   left, then click **Create App Integration**.
3. Select **SAML 2.0** and click **Next**.
4. Enter a name for your application and click **Next**.
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.
6. Click **Next** to go to the **Feedback** screen, fill in
   any necessary details and click **Finish**.

## Configure attribute statements in Okta

After the application is created, configure attribute statements to map
user attributes from Okta to Cube Cloud:

1. In your SAML app integration, go to the **Sign On** tab.

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` |

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

Next, retrieve the values you'll need to complete the configuration
in Cube Cloud:

1. In your SAML app integration, go to the **Sign On** tab.
2. In the sidebar, click **View SAML setup instructions**.
3. Take note of the following values from the setup instructions page:
   * **Identity Provider Single Sign-On URL**
   * **Identity Provider Issuer**
   * **X.509 Certificate**

## Complete configuration in Cube Cloud

Return to the SAML configuration page in Cube Cloud and provide the
identity provider details:

* **Entity ID / Issuer** — Use the **Identity Provider Issuer**
  value from Okta.
* **SSO (Sign on) URL** — Use the **Identity Provider Single
  Sign-On URL** value from Okta.
* **Certificate** — Paste the **X.509 Certificate** from Okta.
* **Auto-provision new users** — When enabled, users are automatically
  created in Cube on their first login via this SAML provider. Enable this
  if you want to provision users only when they first access Cube and you
  are not using SCIM provisioning. New users receive the Viewer role by
  default; see [Default role for new users](#default-role-for-new-users)
  to choose a different role.

## Default role for new users

Auto-provisioned users — both via SAML and via [SCIM][ref-scim] — receive
the **Viewer** role by default. To assign a different role, expand the
**Advanced** section of the SAML configuration form and pick from
**Default role for new users**:

* **Developer**, **Explorer**, or **Viewer** — Cube's [default
  roles][ref-roles].
* Any [custom role][ref-custom-roles] defined in your account, listed
  below the divider.

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.

<Info>
  Admin status is not assignable through this picker — Admin is controlled
  separately. To grant admin permissions, update the user's role manually
  under [Admin → Users][ref-manage-users].
</Info>

<Warning>
  If the selected role is later renamed or deleted, new users will fall
  back to the **Viewer** role until you pick a valid role here. The Viewer
  fallback applies whenever the configured default cannot be resolved —
  whether that's because no default is set or the configured role no longer
  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].

For SAML SSO, group mappings are evaluated **only when a new user is
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
and SCIM group sync.

## Test SAML authentication

1. Copy the **Single Sign-On URL** from the SAML configuration page
   in Cube Cloud.
2. Open a new browser tab and paste the URL into the address bar, then
   press **Enter**.
3. You should be redirected to Okta to log in. After a successful login,
   you should be redirected back to Cube Cloud.

[okta-docs-create-saml-app]: https://help.okta.com/en-us/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm

[ref-scim]: /admin/sso/okta/scim

[ref-roles]: /admin/users-and-permissions/roles-and-permissions

[ref-custom-roles]: /admin/users-and-permissions/custom-roles

[ref-manage-users]: /admin/users-and-permissions/manage-users