# Set up SSO login to the Redox dashboard
We offer **single sign-on** **(****SSO****)** to the Redox dashboard using your own third-party **identity provider** **(****IdP****)**. Redox serves as the **service provider (SP)** in your SSO flow.
SSO helps you control user access policies with a central resource for your organization.
Here are SSO glossary terms for your reference:
Identity provider (IdP)
A third-party system that stores and manages users in your organization. This is useful for anyone that wants to enable SSO for their Redox organization. [Learn how to set up SSO](/how-to-use-redox/manage-your-redox-setup/set-up-sso-login-to-the-redox-dashboard) for your organization.
Some examples of common **identity providers** are Okta, Jumpcloud, Entra, or OneLogin. [Read TrustBuilder‘s docs about identity providers](https://www.trustbuilder.com/what-is-identity-provider).
IdP-initiated login
In terms of SSO, you can initiate a login through your **identity provider** (**IdP**) or the **service provider** (**SP**) can initiate a login.
If SSO is configured to be **IdP-initiated**, it means you must click somewhere in the app to launch SSO login for the service provider.
Some examples of IdP-initiated login are Gmail, Slack, and Salesforce.
Service provider (SP)
A vendor or site that someone wants to log into in order to perform some type of action.
In the Redox world, the Redox dashboard is an example of a **service provider**. Authentication and user management is handled by the **identity provider**.
SP-initiated login
In terms of SSO, you can initiate a login either through your identity provider (IdP) or the service provider (SP) can initiate a login.
If SSO is configured to to be SP-initiated, it means that the vendor or website launches SSO login on your behalf.
An example of SP-initiated login is the Redox dashboard.
## Prerequisites
- Your IdP must support a **SAML protocol**.
- Choose whether to use an **SP-initiated login** (i.e., login initiated from the Redox dashboard) or **IdP-initiated login** (i.e., login initiated from your IdP). Redox supports both, however, IdP-initiated must be enabled for your Redox organization by your Technical Account Manager. SP-initiated is available today by default.
- You must be assigned to an **organization owner role** in Redox to configure SSO. [Learn about user roles](/basics/managing-access-for-your-redox-organization/what-are-user-roles).
- SSO is an **advanced feature** and must be enabled in your Redox organization. Talk to your Technical Account Manager if it’s not enabled.
- SSO is only for single Redox organization users. If your organization has users that are part of multiple Redox organizations, they must remove themselves or transfer access to a different Redox account before using SSO.
- (_Recommended_) Test the SSO configuration with your IdP before enabling SSO in the Redox dashboard. For example, check if users can log in to the IdP as expected. This confirms that your system works with the IdP before adding Redox into the mix.
> **Test before enabling SSO**
>
> If you don’t test before enabling SSO, you risk getting locked out of your Redox organization.
## Step 1: Configure SSO in the Redox dashboard
If you’re an organization owner, follow these steps to enable SSO.
1. Log in to the Redox dashboard.
2. In the bottom-left navigation menu, click **your username** to open the user menu.
3. From the user menu, select the **Organization profile** option**.**
4. By default, the Organization info page displays. Click the **Settings** tab.
5. The SSO information displays. First, we provide the Redox authorization server values. Use the **Connection name value** and **Audience restriction value** in your IdP configuration.
*Redox authorization server values*
6. Next, the Identity provider configuration contains details about your IdP. Specific configuration details vary between IdPs, but the basic process is the same. Fill in the relevant fields:
- Name: Enter a **human-readable name** to represent your IdP.
- Domain name: This field automatically populates with the company domain and isn’t editable. The domain is where your organization’s users have an email account.
- Configuration mode: Select either the **URL Import** or **Manual** option.
- **URL import**: Enter the public URL for your SAML metadata XML document. Redox pulls the entity ID and keys to validate the response from the IdP.
*IdP configuration - Import option*
- **Manual**: Provide the entity ID and keys yourself.
- Signing certificate: Enter the **public key** that your IdP uses to sign requests. This should be an X.509 certificate encoded in PEM or CER format. Review the instructions for locating and downloading the certificate for your relevant IdP in the Step 2 section.
- Sign-in URL: Enter the **redirect URL** for your users to log in to the IdP.
> **Redox Sign-in URL vs. IdP Sign-in URL**
>
> You must enter a **Sign-in URL** in both the Redox dashboard and your IdP, but these URLs shouldn’t be the same.
>
> - The Sign-in URL in the Redox dashboard _should point to your IdP_.
> - The Sign-in URL in the IdP _should point to the Redox dashboard_.
*IdP configuration - Manual option*
7. Confirm the Attribute mapping. These fields populate automatically, but you should confirm them or adjust as needed.
*IdP configuration - Attribute mapping*
- User full name: The name of the SAML attribute that your IdP uses for a user’s full name.
- User email: The name of the SAML attribute that your IdP uses for a user’s email address.
8. Click the **Save** button.
9. When successfully saved, the Enabled for Organization toggle appears and is set to ON.
To disable SSO later, toggle this option to OFF.
*SSO enabled for your organization*
10. Next, configure the SAML protocol. We provide instructions for some common IdPs in the Step 2 section.
## Step 2: Configure SAML protocol in your IdP
We provide instructions to configure the SAML protocol for common IdPs.
> **Where to find the Connection URL**
>
> You can find the `Connection` URL in the Redox dashboard. The value is specific to your Redox organization’s IdP configuration.
For Okta
#### Create a new app
1. Log in to your Okta admin dashboard.
2. Click the **Applications** tab, then the **Integration network** option.
3. On the Integration network page, click the **Create a New App** button.
4. The Create a new app integration page opens. Select the **SAML 2.0** option, then click the **Next** button.
*Okta: Create a new app integration page *
#### General Settings
The General Settings opens.
1. Enter an **App name** for your SAML protocol, then click the **Next** button.
*Okta: App general settings*
#### SAML Settings
The SAML Settings opens.
1. Enter the following values:
1. Single sign on URL: The Redox auth URL
(**https://auth-v2.redoxengine.com/login/callback?connection=\**)
2. Audience URI: The intended audience of the SAML assertion
(**urn:auth0:redoxprod:\**).
Copy and paste the **Audience restriction value** from the Redox dashboard (see step #5 in the Step 1 section).
*Okta: App SAML settings*
2. Scroll down to the Attribute Statements settings and add the following statements.
1. Add a statement for the **email address attribute**:
- Name: The attribute name
(**http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress**)
- Name format: The specified format for the name
(**Unspecified**)
- Value: The name value
(**user.email**)
2. Add a statement for the **name attribute**:
- Name: The attribute name
(**http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name**)
- Name format: The specified format for the name
(**Unspecified**)
- Value: The name value
(**user.firstName+" "+user.lastName**)
*Okta: SAML settings - Attribute statements*
3. Once the SAML settings are populated, click the **Next** button.
#### Create an internal app
1. On the next page, select the **I'm an Okta customer adding an internal app** option.
2. Another set of options appears. Select the **This is an internal app that we have created** option, then click the **Next** button.
3. On the next page, click the **Sign On** tab.
#### Sign On option: URL import option in the Redox dashboard
If you chose Configuration mode - URL Import option in the Redox dashboard (step #6 in Step 1 section), complete the following steps in both Okta and the Redox dashboard.
In Okta:
1. In the SAML Signing Certificates section, your active signing certificate appears. Click the **Actions** drop-down menu, then click the **View IDP metadata** option.
*Okta: View IdP metadata for URL import option*
2. In the new tab, copy the **metadata URL**.
In the Redox dashboard, under the Organization Profile \> Settings \> Identity Provider Configuration section:
1. Paste the Okta **metadata URL** into the SAML metadata URL field.
*Redox: IdP configuration - URL import option*
2. Scroll down and click the **Save** button.
#### Sign On option: Manual option in the Redox dashboard
If you chose Configuration mode - Manual option in the Redox dashboard (step #6 in Step 1 section), complete these steps:
In Okta:
1. In the SAML Signing Certificates section, your active signing certificate appears. Click the **Actions** drop-down menu, then click the **Download certificate** option.
*Okta: Download signing certificate to populate the Redox public key*
2. Click the **Actions** drop-down menu, then click the **View IdP metadata** option.
3. A new tab opens. Copy the **Identity Provider Single Sign-on URL** to paste in the Redox dashboard.
In the Redox dashboard, under the Organization Profile \> Settings \> Identity Provider Configuration section:
1. Copy and paste the downloaded **SAML Signing Certificate value** as the public key in the Signing certificate field.
2. Paste the **Identity Provider Single Sign-on URL** in the Sign-in URL field.
*Redox: IdP configuration - Manual option*
3. Scroll down and click the **Save** button.
After completing all these sections, go back to the Okta admin dashboard to start assigning users to the Redox application.
For Microsoft Azure Active Directory
1. Log in to your Azure portal.
2. Navigate to the **Azure Active Directory** page.
3. The directory’s Overview page opens. On the navigation menu, click the **Enterprise applications** page.
4. All of your applications display on the page. Click the **New application** button.
5. The Browse Azure AD Gallery page opens. Click the **Create your own application** button.
6. A modal opens for your new application. Enter a **human-readable name** for the Redox dashboard application.
7. Then, select the **Integrate any other application you don**’**t find in the gallery (Non-gallery)** option.
8. Click the **Create** button.
*Create your own Azure application*
9. The enterprise application Overview page opens. Click the **Set up single sign on** option.
10. The Single sign on page opens. Click the **SAML** option.
11. The SAML-based Sign-on settings opens. For the Basic SAML Configuration option, click the **Edit** button.
*Edit the SAML settings*
12. The Basic SAML Configuration modal opens. Enter the SAML settings:
- Click the **Add identifier** link and replace the default identifier ID (entity ID) with the new identifier: **urn:auth0:redoxprod:\**.
- Click the **Add reply URL** link and enter the Redox auth URL:
**https://auth-v2.redoxengine.com/login/callback?connection=\**.
- After both values are entered, click the **Save** button at the top.
*SAML settings*
13. The modal closes. Back on the SAML-based Sign-on settings, click the **Edit** button for the Attributes & Claims option.
*Edit the Attributes & Claims*
14. The Redox dashboard currently requires claims for the user’s name and email address. Use the default SAML claims configured in the Azure active directory application, or modify them to meet your organization’s needs. The defaults are the following:
- Email: **http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress**.
- Name: **http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name**.
15. Back on the SAML-based Sign-on settings, locate the **App Federation Metadata URL** under the SAML Signing Certificate option.
16. _If you chose_ _Configuration mode - URL Import option_ _in the Redox dashboard_ (step #6 in Step 1 section), copy the **metadata URL** and paste it into the SAML metadata URL field (under Redox Organization Profile \> Settings \> Identity Provider Configuration section).
*Microsoft Azure: Copy the metadata URL*
17. _If you chose_ _Configuration mode - Manual option_ _in the Redox dashboard_ (step #6 in Step 1 section), complete these steps:
1. Copy and paste the Microsoft Azure **Sign On URL value** in the Sign-in URL field (under Redox Organization Profile \> Settings \> Identity Provider Configuration section).
2. Download the Microsoft Azure **Certificate (Raw)** and paste the value in the Signing Certificate field (under Redox Organization Profile \> Settings \> Identity Provider Configuration section).
## Step 3: Enable IdP-initiated login
This step is only required if you choose IdP-initiated login. For SP-initiated users, skip to step 4.
Follow these steps only after completing steps 1 and 2, since IdP-initiated login requires SP-initiated SSO to already be configured.
1. Talk to your Technical Account Manager to have them enable IdP-initiated login for your Redox organization.
2. Redox configures your organization to accept unsolicited SAML assertions from your IdP.
3. Once enabled, set up an app tile/link in your IdP pointing to your Redox organization. Your users will be able to log in directly from there.
4. After creating the app in your IdP, assign any users to that app to enable them to log in.
## Step 4A: Log in to the Redox dashboard (SP-initiated)
Once SSO is successfully enabled in both the Redox dashboard and your IdP, all users must log in with SSO. Any previous Redox credentials will no longer work.
1. Navigate to the Redox dashboard.
2. Enter your **email address** in the login page.
3. You’re redirected to your IdP for authentication.
1. If successful, you’re redirected back to the Redox dashboard as a logged-in user.
2. If unsuccessful, [refer to our troubleshooting tips](/troubleshooting/troubleshoot-sso-errors).
> **How users are handled in your IdP**
>
> Any new user who successfully authenticates with your IdP is added to your Redox organization. User access can be revoked by your IdP at any time.
>
> Existing users of your organization may not join another Redox organization.
## Step 4B: Log in to the Redox dashboard (IdP-initiated)
Once SSO is successfully enabled in both the Redox dashboard and your IdP, all users must log in with SSO. Any previous Redox credentials will no longer work.
1. Navigate to your IdP.
2. In your app login options, click the **Redox** tile.
3. Complete your IdP authentication.
4. The Redox dashboard opens with an authenticated session.