Okta SSO Setup

Set up the RudderStack SSO (Single Sign-On) feature with Okta.

Available Plans

enterprise

6 minute read

The Single Sign-On (SSO) feature is available in the Enterprise plan only.

The Okta RudderStack app is available on the Okta Integration Network (OIN). This guide lists the steps to set up the integration.

Note that:
RudderStack supports only the SAML 2.0 protocol for SSO.
You can refer to the Okta Manual Setup guide to manually configure and enable Okta SSO for your organization.
If you are anticipating any changes to your SSO like email change, make sure to contact RudderStack support in advance to avoid any login issues.

Supported features

The Okta-RudderStack SAML integration supports the following features:

SP-initiated SSO
JIT(Just In Time) Provisioning

For more information on these features, see Okta Glossary.

Also, it supports the following SAML attributes:

Name	Value
FirstName	user.firstName
LastName	user.lastName
Email	user.email

Step 1: Add the RudderStack SSO SAML 2.0 app

Before you enable SAML, note that:
Your users will not be able to sign in to RudderStack through their regular sign-in page once SAML is enabled. They will be able to access RudderStack only through the Okta service.
RudderStack does not provide a backup sign-in URL where users can log in with their username and password.
You can contact RudderStack support to disable SAML, if required.

Log in to Okta as an administrator.
Go to the RudderStack SSO integration page. Then, click Add Integration:

Select the account under Choose an account.
Set the Application Label (your preferred application name) and the Application Visibility. Check the Do not display application icon to users and Do not display application icon in the Okta Mobile App settings, as shown. Then, click Next.

Since the integration supports only SP-initiated flow, hiding the application icon for the users is highly recommended.

You need to check the Do not display application icon to users and Do not display application icon in the Okta Mobile App settings as this app will not be visible to your users.

Under Sign on methods, choose SAML 2.0.
Under Metadata details, copy the Metadata URL.
Under Credentials Details, set Application username format to Email. Retain the rest of the settings and click Done.

Before sharing the Metadata URL, verify that the IdP metadata declares both HTTP-Redirect and HTTP-POST SAML bindings.
RudderStack uses AWS Cognito, which sends the initial login request with HTTP-Redirect, so metadata that advertises only HTTP-POST will be rejected.

Share the Metadata URL copied above with the RudderStack team to enable SAML 2.0 for your account.

When you contact the RudderStack team to enable SSO, also tell them how to add new users to your organization, and which workspace (if any) to set as the default workspace that new users land in:
Auto-add SSO users Default workspace New user signing in through SSO User activated through SCIM (Okta and Azure Entra ID)
Off Not applicable Not added to your organization Added to your organization with no workspace access
On Not set Added to your organization with no workspace access Added to your organization with no workspace access
On Set Added to your organization with access to the default workspace Added to your organization with access to the default workspace
Note that:
For Okta and Azure Entra ID, SCIM activation always adds the user to your organization, even when auto-add is off.
A user with no workspace access sees a message that access hasn’t been granted yet, until an admin gives them access to a workspace.
You can also ask the team to create a personal organization for each new SSO user. This is off by default.

Auto-add SSO users	Default workspace	New user signing in through SSO	User activated through SCIM (Okta and Azure Entra ID)
Off	Not applicable	Not added to your organization	Added to your organization with no workspace access
On	Not set	Added to your organization with no workspace access	Added to your organization with no workspace access
On	Set	Added to your organization with access to the default workspace	Added to your organization with access to the default workspace

Step 2: Add the RudderStack SSO Bookmark app

Your users will use this app to quickly access the RudderStack dashboard using the SSO functionality.

To create the SSO bookmark app in Okta:

Go to the RudderStack SSO integration page. Then, click Add Integration:

Set the Application Label that you set previously. Then, click Next.

Do not check the Do not display application icon to users and Do not display application icon in the Okta Mobile App settings as this app will be visible to your users.

Under Sign on methods, choose Bookmark-only. Set the Login URL to https://app.rudderstack.com/sso?domain=<your_website>, where <your_website> is your organization’s web domain. Under Credentials Details, set Application username format to Email. Retain the rest of the settings and click Done.

User authentication

Once you have set up SSO, the users can authenticate to RudderStack through any of the below approaches:

The bookmark app set up in Step 3.
SP-initated SSO by following these steps:
1. Go to https://app.rudderstack.com/sso.
2. Enter your email address and click SIGN IN.

SCIM configuration

You can automatically grant RudderStack access to your users by configuring SCIM provisioning in Okta.

Debugging

There are times when an SSO login might fail for some users due to some reason. In such cases, the RudderStack team requires a HAR (HTTP Archive) file to inspect the requests and identify any SSO-related issues.

A HAR file is a log of exported network requests from the user’s browser. See the HAR Analyzer guide for steps on generating this file depending on your browser.

Once you generate the HAR file, share it with the RudderStack team to troubleshoot the issue.

Note the following before capturing your HAR file:
Start from https://app.rudderstack.com/sso with a clean session, preferably in incognito mode of your browser.
Complete the SSO flow until the step where you face an error.
Your HAR file might contain sensitive data - make sure to redact it using a text editor before sharing it with the team.

The following sections contain solutions for some common errors you might encounter while setting up SSO:

Invalid samlResponse or relayState from identity provider

The above error indicates you tried the IdP-initiated authentication flow. As stated above, this integration supports only Service Provider (SP)-initiated SSO flow.

RudderStack recommends initiating the SSO authentication by following all the above SSO configuration steps correctly.

As an alternative, you can simulate the IdP-initiation authentication flow by using the Okta Bookmark app and setting the Login URL to https://app.rudderstack.com/sso?domain=<your_website>, where <your_website> is your organization’s web domain.

Required String parameter ‘RelayState’ is not present

The above error indicates that you did not set up your SSO app correctly. Make sure to:

Set the Audience URI (SP Entity ID) field to urn:amazon:cognito:sp:us-east-1_ABZiTjXia.
Configure the other SAML settings correctly.

FAQ

My organization’s email domain has changed from `abc.com` to `xyz.com` and now I am unable to log in. What should I do?

Contact RudderStack support to make the necessary changes to your SSO configuration.