# Okta SSO Manual Setup


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

This guide lists the steps to **manually** configure and enable Okta SSO for your organization.

{{< info >}}
Note that:

- RudderStack supports only the [SAML 2.0 protocol](https://auth0.com/intro-to-iam/what-is-saml) for SSO.
- RudderStack does not support IdP-initiated authentication. To use Okta SSO for your organization, you need to log in through [this link](https://app.rudderstack.com/sso).
{{< /info >}}

## Configuring the RudderStack SSO App

1. Log in to your Okta application as an **administrator**. Then, go to the **Applications** page in the dashboard.
2. Click the **Create App Integration** button to integrate Okta with RudderStack:

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

3. Select **SAML 2.0** sign-in method:

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

4. Under **General Settings**, set the **App name** to **RudderStack**, as shown. Then, click **Next**.

{{< image src="images/user-guides/okta-sso-3.webp" alt="RudderStack as app name" >}}

### SAML settings

Enter the following settings in the **Configure SAML** section:

{{< image src="images/user-guides/okta-sso-4.webp" alt="Enter the settings" >}}

- **Single sign on URL**: Set this to `https://auth2.rudderstack.com/saml2/idpresponse`.

{{< info >}}
Make sure you also enable the **Use this for Recipient URL and Destination URL** option under this setting.
{{< /info >}}

- **Audience URI (SP Entity ID)**: Set this to `urn:amazon:cognito:sp:us-east-1_ABZiTjXia`.
- **Default RelayState**: Leave this field blank.
- **Name ID format**: Select **Unspecified** from the dropdown, which defaults to email.
- **Application username**: Select **Okta username** from the dropdown.
- **Update application username on**: Select **Create and update** from the dropdown.

### Attribute Statements settings

In the **Attribute Statements** section, you need to enter the following settings:

{{< image src="images/user-guides/okta-sso-5.webp" alt="Identity provider metadata" >}}

| Name              | Name format (optional) | Default value            | Comments |
| :---------------- | :----------------------- | :--------------- | :-----|
| Email         | Unspecified              | `user.email` | Set the value corresponding to **your organization's** user email. |
| LastName          | Unspecified              | `user.lastName`  |  Although `user.lastName` is recommended, you can provide any other value here. | 

{{< info >}}
As long as the attributes you set match the **Email** and **LastName** fields, your SSO app will work without any issues.
{{< /info >}}

In the next page, select the **I'm an Okta customer adding an internal app** option and click **Finish**.

The RudderStack Single Sign-On app is now created and you will be directed to the app's page.

## Enabling SSO

The RudderStack SSO app supports dynamic configuration. 

In the **Sign On** section of the RudderStack SSO app, right click and copy the URL associated with **Identity Provider metadata** under the **View Setup Instructions** button, as shown in the below image. 

{{< image src="images/user-guides/okta-sso-6.webp" alt="Identity provider metadata" >}}

{{< warning >}}
Before sharing the Identity Provider 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 >}}

Share this URL with the RudderStack team to enable SSO for your organization.

{{< info >}}
The **Identity Provider metadata** URL ends with `/metadata`.
{{< /info >}}

{{< 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 >}}

## SCIM configuration steps

This section lists the steps to configure SCIM provisioning in Okta.

### Prerequisites

Before setting up SCIM provisioning,  make sure to generate an [organization-level Service Access Token]({{< ref "access-management/service-access-tokens.md#organization-sat" >}}) in the RudderStack workspace for which you want to enable SCIM.

{{< warning >}}
Make sure to create an **organization-level** Service Access Token. Otherwise, your SCIM provisioning tasks will fail.
{{< /warning >}}

#### Token permissions for legacy RBAC system

If you are on the [legacy Permissions Management (RBAC) system]({{< ref "archive/dashboard-guides/user-management.md" >}}), generate an [Organization-level Service Access Token]({{< ref "archive/dashboard-guides/service-access-tokens.md#generate-service-access-token" >}}).

### SCIM configuration

1. Log in to Okta as an administrator.
2. In the sidebar, go to **Applications** > **Applications** and select your SSO app.
3. Go to the **General** tab, click **Edit** and check the **Enable SCIM provisioning** option: 

{{< image src="images/user-guides/scim-1.webp" alt="Enable SCIM provisioning" >}}

4. A new tab called **Provisioning** will now be visible in the app settings. Go to **Integration**, click **Edit** and enter the following details:

| Setting | Value |
| :------| :-------|
| SCIM connector base URL | `https://api.rudderstack.com/scim/v2` |
| Unique identifier field for users | `userName` |
| Supported provisioning actions | Check the following settings: <br /><br /><ul><li>Push New Users</li><li>Push Profile Updates</li></ul> |
| Authentication Mode | `HTTP Header` |

{{< image src="images/user-guides/scim-2.webp" alt="SCIM provisioning settings" >}}

5. Under **HTTP Header**, paste your [Service Access Token](#prerequisites) obtained above.
6. Click **Save**. Okta will send a test request to verify the configuration.
7. Once the verification is complete, you will be able to see two new options, **To App** and **To Okta**, in the **Settings** sidebar:

{{< image src="images/user-guides/scim-3.webp" alt="Settings sidebar" >}}

8. Go to the **To App** settings and click **Edit**. Then, enable the following **Provisioning to App** settings:

{{< image src="images/user-guides/scim-4.webp" alt="App provisioning settings" >}}

9. Scroll down to the attribute mappings section and click **Show Unmapped Attributes**. 
10. Unmap all attributes one by one by clicking the **X** icon, **except** the following mandatory attributes:
    - **Display name**
    - **Email**

{{< info >}}
When Okta sends a request to create a user, it assumes that the update has failed if the response does not contain the details of the mapped attributes. Hence, you must unmap all attributes except **Display name** and **Email**.
{{< /info >}}

11. For **Display name** and **Email**, click the edit icon and set the  **Apply on** field to **Create and update**.

{{< image src="images/user-guides/scim-5.webp" alt="Display name and email configuration" >}}

{{< info >}}
The **Value** fields for **Display name** and **Email** may vary depending on how you have set up your Okta app.
{{< /info >}}

12. Click **Save** to finish the configuration.
13. Go back to your app settings, click the **Sign On** tab and click **Edit**.
14. Under **Credentials Details**, set **Application username format** to **Email**:

{{< image src="images/user-guides/scim-6.webp" alt="Sign on settings" >}}

15. Finally, click **Save**.

{{< info >}}
RudderStack currently does not support some SCIM features like importing users or groups, removing users, or snycing passwords. Refer to the [Known issues]({{< ref "user-guides/sso-setup/okta/scim-configuration.md#known-issues" >}}) section for more information.
{{< /info >}}

## 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]({{< ref "user-guides/sso-setup/okta/_index.md#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.