# OneLogin SSO 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 configure and enable OneLogin SSO for your organization.

{{< info >}}
RudderStack supports only the [SAML 2.0 protocol](https://auth0.com/intro-to-iam/what-is-saml) for SSO.
{{< /info >}}

## Configure RudderStack SSO app

1. Log into your [OneLogin portal](https://app.onelogin.com/login) and click **Administration** in the top menu:

{{< image src="images/user-guides/onelogin-1.webp" alt="Administration option in OneLogin" >}}

2. From the top menu, go to **Applications** > **Applications**:

{{< image src="images/user-guides/onelogin-2.webp" alt="Applications option" >}}

3. Then, click **Add App**:

{{< image src="images/user-guides/onelogin-3.webp" alt="Add App option" >}}

4. In the resulting **Find Applications** page, search for **SAML Custom Connector (Advanced)**. From the search results, select the application:

{{< image src="images/user-guides/onelogin-4.webp" alt="Select SAML Custom Connector option" >}}

5. Name your SAML app and click **Save**:

{{< image src="images/user-guides/onelogin-5.webp" alt="Select SAML app name" >}}

6. In the **Configuration** tab, enter the settings as shown in the following image:

{{< image src="images/user-guides/onelogin-6.webp" alt="SAML app configuration" >}}

The settings to be configured are listed in the following table:

| Setting | Value |
| :-------| :------|
| Audience (EntityID) | `urn:amazon:cognito:sp:us-east-1_ABZiTjXia` |
| Recipient | `https://auth2.rudderstack.com/saml2/idpresponse` |
| ACS (Consumer) URL Validator | `^https:\/\/auth2\.rudderstack\.com\/saml2\/idpresponse\/\$` |
| ACS (Consumer) URL | `https://auth2.rudderstack.com/saml2/idpresponse` |
| Login URL | `https://app.rudderstack.com/sso?domain=<your_website>` |

{{< warning >}}
Make sure you enter the correct domain name in the **Login URL** setting. 

For example, if your employee email is `john@example.com`, then your **Login URL** will be `https://app.rudderstack.com/sso?domain=example.com`.
{{< /warning >}}

7. From the dropdown, select the **SAML initiator** and **SAML nameID format** fields as shown:

{{< image src="images/user-guides/onelogin-7.webp" alt="SAML settings" >}}

{{< success >}}
Configure the other SAML settings related to the assertion validity, encryption method, etc. as per your organizational requirements.
{{< /success >}}

8. Next, go to the **Parameters** tab and add the custom parameters as shown below:

{{< image src="images/user-guides/onelogin-8.webp" alt="Custom parameters" >}}

The custom parameters and their values are listed in the following table:

| Parameter | Value |
| :-------| :------|
| Email | `Email` |
| LastName | `Name` |
| NameID value | `Email` |

{{< info >}}
For the **LastName** custom attribute, you can specify a single field `Name` - which specifies how you would like to see your employees on the RudderStack web app.
{{< /info >}}

9. To add any other custom parameter, click the **+** button, enter the **Field name**, and select the value from the dropdown:

{{< image src="images/user-guides/onelogin-9.webp" alt="Custom parameter configuration" >}}

{{< warning >}}
Make sure you enable (tick) the **Include in SAML assertion** flag for each custom parameter.
{{< /warning >}}

10. Click **Save** to save the configuration.

## Enable SSO

Go to the **SSO** tab of your app and copy the **Issuer URL**:

{{< image src="images/user-guides/onelogin-10.webp" alt="Issuer URL" >}}

{{< success >}}
The **Issuer URL** is the SAML metadata endpoint that contains the certificate and any other information required to enable SSO for your organization.
{{< /success >}}

{{< warning >}}
Before sharing the Issuer 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 **Issuer URL** with the RudderStack team.

{{< info >}}
While sharing the Issuer 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 >}}

## 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 [configuring the RudderStack SSO app](#configure-rudderstack-sso-app) and setting the **Login URL** field to `https://app.rudderstack.com/sso?domain=<your-website>]` where `<your_website>` is your organization’s web domain.

{{< image src="images/user-guides/onelogin-6.webp" alt="SAML app configuration" >}}

#### 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 (EntityID)** field to `urn:amazon:cognito:sp:us-east-1_ABZiTjXia`.
- Set the **SAML nameID format** to **Email**.
- Configure the other SAML settings (Step 6 under [Configure RudderStack SSO app](#configure-rudderstack-sso-app)) correctly.

## FAQ

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