SAML authentication with Okta

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.

</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 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 to choose a different role.

Default role for new users

Auto-provisioned users — both via SAML and via 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.
• Any custom role 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. It is applied in addition to any roles your identity provider sends via the role attribute (subject to the rolesMap).

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

</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.
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.

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