Okta SSO Setup

Set up the RudderStack SSO (Single Sign-On) feature with Okta.
Available Plans
  • enterprise

  •   4 minute read  

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

info
  • To manually configure and enable Okta SSO for your organization, see the Manual Setup guide.
  • 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:

NameValue
FirstNameuser.firstName
LastNameuser.lastName
Emailuser.email

Step 1: Add the RudderStack SSO SAML 2.0 app

warning

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.
  1. Log in to Okta as an administrator.
  2. Go to the RudderStack SSO integration page. Then, click Add Integration:
Add Integration
  1. Select the account under Choose an account.
  2. 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.
warning
Since the integration supports only SP-initiated flow, hiding the application icon for the users is highly recommended.
Application name and visibility
info
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.
  1. Under Sign on methods, choose SAML 2.0.
  2. Under Metadata details, copy the Metadata URL.
  3. Under Credentials Details, set Application username format to Email. Retain the rest of the settings and click Done.
SAML 2.0 configuration
  1. Share the Metadata URL copied above with the RudderStack team to enable SAML 2.0 for your account.

Step 2: Add the RudderStack SSO Bookmark app

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

To create the SSO bookmark app in Okta:

  1. Go to the RudderStack SSO integration page. Then, click Add Integration:
Add Integration
  1. Set the Application Label that you set previously. Then, click Next.
warning
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.
Application name and visibility
  1. Under Sign on methods, choose Bookmark-only. Set the Login URL to https://app.rudderstack.com/sso?domain=<your_website>.com, 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.
Bookmark sign on method and Login URL

User authentication

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

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.

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

warning

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.

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.


Questions? Contact us by email or on Slack