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.
Note that:
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.
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.
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
Your users will use this app to quickly access the RudderStack dashboard using the SSO functionality.
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>.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.
User authentication
Once you have set up SSO, the users can authenticate to RudderStack through any of the below approaches:
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
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.
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.