# Okta SSO Setup


{{< announcement >}}
The Single Sign-On (SSO) feature is available in the [Enterprise](https://www.rudderstack.com/enterprise-quote/) plan only.
{{< /announcement >}}

The [Okta RudderStack app](https://www.okta.com/integrations/rudderstack/) is available on the **Okta Integration Network (OIN)**. This guide lists the steps to set up the integration.

{{< info >}}
Note that:

- RudderStack supports only the [SAML 2.0 protocol](https://auth0.com/intro-to-iam/what-is-saml) for SSO.
- You can refer to the [Okta Manual Setup]({{< ref "user-guides/sso-setup/okta/manual-setup.md" >}}) 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](mailto:support@rudderstack.com) in advance to avoid any login issues.
{{< /info >}}

## 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](https://help.okta.com/en/prod/Content/Topics/Reference/glossary.htm).

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

{{< 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](mailto:support@rudderstack.com) to disable SAML, if required.
{{< /warning >}}

1. [Log in to Okta](https://www.okta.com/login/) as an administrator.
2. Go to the [RudderStack SSO integration page](https://www.okta.com/integrations/rudderstack/). Then, click **Add Integration**:

{{< image src="images/user-guides/rudderstack-okta-sso-1.webp" alt="Add Integration" >}}

3. Select the account under **Choose an account**.
4. 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.
{{< /warning >}}

{{< image src="images/user-guides/rudderstack-okta-sso-2.webp" alt="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.
{{< /info >}}

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

{{< image src="images/user-guides/rudderstack-okta-sso-8.webp" alt="SAML 2.0 configuration" >}}

{{< warning >}}
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.
{{< /warning >}}

8. Share the **Metadata URL** copied above with the [RudderStack team](mailto:support@rudderstack.com) to enable SAML 2.0 for your account.

{{< info >}}
While sharing the metadata URL, also let the RudderStack team know:

- Which workspace you would like to set as the **default workspace** for your organization. New users who sign in through SSO for the first time will automatically land in this workspace.
- Whether you want RudderStack to also create a **personal organization** for each new SSO user. This is **off by default**.

You can also opt out of setting up a default workspace altogether if you don't want your SSO users to get automatic access to a shared workspace.
{{< /info >}}

## Step 2: Add the RudderStack SSO Bookmark app

{{< info >}}
Your users will use this app to quickly access the [RudderStack dashboard](https://app.rudderstack.com/) using the SSO functionality.
{{< /info >}}

To create the SSO bookmark app in Okta:

1. Go to the [RudderStack SSO integration page](https://www.okta.com/integrations/rudderstack/). Then, click **Add Integration**:

{{< image src="images/user-guides/rudderstack-okta-sso-1.webp" alt="Add Integration" >}}

2. 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.
{{< /warning >}}

{{< image src="images/user-guides/rudderstack-okta-sso-5.webp" alt="Application name and visibility" >}}

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

{{< image src="images/user-guides/rudderstack-okta-sso-9.webp" alt="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:

- The bookmark app set up in [Step 3](#step-3-add-the-rudderstack-sso-bookmark-app).
- [SP-initated SSO](#supported-features) 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]({{< ref "user-guides/sso-setup/okta/scim-configuration.md" >}}) in Okta.

## Debugging

{{< customreadfile "/includes/sso-debugging.md" >}}

#### Invalid samlResponse or relayState from identity provider

{{< image src="images/user-guides/sso-errors-1.webp" alt="SSO errors" >}}

The above error indicates you tried the [IdP](https://support.okta.com/help/s/article/okta-saml?language=en_US)-initiated authentication flow. As stated above, this integration supports only [Service Provider (SP)-initiated SSO flow](#supported-features).

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](#step-2-add-the-rudderstack-sso-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.

{{< image src="images/user-guides/sso-errors-3.webp" alt="SSO errors" >}}

#### Required String parameter 'RelayState' is not present

{{< image src="images/user-guides/sso-errors-2.webp" alt="SSO errors" >}}

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]({{< ref "user-guides/sso-setup/okta/manual-setup.md#saml-settings" >}}) correctly.

## FAQ

{{< customreadfile "/includes/sso-faq.md" >}}