# Set up SSO login to the Redox dashboard

We offer <u>**single sign-on**</u> **(**<u>**SSO**</u>**)** to the Redox dashboard using your own third-party <u>**identity provider**</u> **(**<u>**IdP**</u>**)**. Redox serves as the <u>**service provider (SP)**</u> 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:

<details>
<summary>Identity provider (IdP)</summary>

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 <u>**identity providers**</u> are Okta, Jumpcloud, Entra, or OneLogin. [Read TrustBuilder‘s docs about identity providers](https://www.trustbuilder.com/what-is-identity-provider).

</details>

<details>
<summary>IdP-initiated login </summary>

In terms of SSO, you can initiate a login through your <u>**identity provider**</u> (<u>**IdP**</u>) or the <u>**service provider**</u> (<u>**SP**</u>) can initiate a login.  

If SSO is configured to be <u>**IdP-initiated**</u>, 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. Redox supports IdP-initiated login for open beta users. 

</details>

<details>
<summary>Service provider (SP)</summary>

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 <u>**service provider**</u>. Authentication and user management is handled by the <u>**identity provider**</u>.

</details>

<details>
<summary>SP-initiated login</summary>

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 default login type of the Redox dashboard. 

</details>

## Prerequisites

- Your IdP must support a <u>**SAML protocol**</u>.
- Choose whether to use an <u>**SP-initiated login**</u> (i.e., login initiated from the Redox dashboard) or <u>**IdP-initiated login**</u> (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 <u>**organization owner role**</u> in Redox to configure or edit SSO. [Learn about user roles](/basics/managing-access-for-your-redox-organization/what-are-user-roles-and-groups).
- SSO is an <u>**advanced feature**</u> and must be enabled in your Redox organization. Talk to your Technical Account Manager if it’s not enabled.
- SSO is only for <u>single Redox organization users</u>. 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 <u>organization owner</u>, 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 <u>Organization info</u> page displays. Click the **Settings** tab.
5. Under the <u>Single sign-on</u> section, click the **Configure** button. 
6. The SSO form opens. Under <u>Redox authorization server values</u>, we provide the **Connection name value** and **Audience restriction value**. Use these values in your IdP configuration. 
7. Next, the <u>Identity provider configuration</u> contains details about your IdP. Specific configuration details vary between IdPs, but the basic process is the same. Fill in the relevant fields:
   - <u>Name</u>: Enter a **human-readable name** to represent your IdP (e.g., Okta).
   - <u>Domain name</u>: This field automatically populates with the company domain and isn’t editable. The domain is where your organization’s users have an email account.
   - <u>Configuration mode</u>: Select either the **URL Import** or **Manual** option.  
     - <u>**URL import**</u>: Enter the public URL for your SAML metadata XML document. Redox pulls the entity ID and keys to validate the response from the IdP. 
     - <u>**Manual**</u>: Provide the entity ID and keys yourself.
       - <u>Signing certificate</u>: 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 <u>Step 2</u> section. 
       - <u>Sign-in URL</u>: 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 <u>**Sign-in URL**</u> 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_.


8. Under the <u>Mapping</u> section, the <u>Identity attributes</u> populate automatically, but you should confirm them or adjust as needed.
   - <u>User full name</u>: The name of the SAML attribute that your IdP uses for a user’s full name.
   - <u>User email</u>: The name of the SAML attribute that your IdP uses for a user’s email address.
9. (Optional) Under the <u>Mapping</u> section, fill out the <u>Identity provider groups</u> to map your IdP groups to Redox groups. This doesn’t add the IdP member to the Redox group; instead, it grants your IdP members the roles assigned to the Redox group upon sign-in.


> **Configuring your IdP groups**
>
> Refer to your IdP docs for configuring groups and getting group attributes or values:
>
> - [Okta groups](https://help.okta.com/en-us/Content/Topics/Apps/define-group-attribute-statements.htm)
> - [Microsoft Entra ID groups](https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims)


   1. Enter the **groups attribute**, which is the attribute your IdP uses to send group names (e.g., typically `groups` or `memberOf`). Leave this empty if you don’t map any groups.  
   2. Click the **Add mapping** button. 
   3. In the new field, enter the name of the **identity provider group** (matching is exact and case sensitive). Then select the **Redox group** to map to from the drop-down field.
   4. Click the **Add mapping** button again to map additional IdP groups (up to 100). 


> **Mapping to two Redox groups**
>
> You can map the same IdP group to two Redox groups. Doing so grants the roles of both groups.


10. (Optional) Under <u>Organization settings</u>, toggle the **Enable for Organization** to ON to apply the SSO settings right away. Leave this OFF if you want to complete any other testing or setup prior to turning on SSO for all your users.   
11. Click the **Create** button. 
Any group mappings or settings take effect the next time an IdP member signs in. 

## Step 2: Configure SAML protocol in your IdP

Refer to the docs for configuring SAML settings for your selected IdP:

- [Okta SAML settings](https://support.okta.com/help/s/article/How-To-Configure-A-Custom-SAML-App?language=en_US)
- [Microsoft Entra ID SAML settings](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/add-application-portal-setup-sso)

Remember that you’ll need the <u>Redox authorization server values</u> (**connection name** and **audience restriction**) from the SSO settings in Redox dashboard. The server values are unique to your Redox organization. 

> **SP-initiated vs. IdP-initiated login**
>
> By default, Redox supports SP-initiated login. This means when you log in to the Redox dashboard, we redirect you to your IdP for authentication, then direct you back to the Redox dashboard once authenticated.
>
> _For open beta users_, Redox also supports IdP-initiated login. This means you can click a Redox tile in your Okta or Microsoft Entra ID dashboard without visiting the Redox login page first. This launches you directly in an authenticated Redox dashboard session. Talk to your Technical Account Manager to enable IdP-initiated login.
>

## Step 3: Enable IdP-initiated login

> **Open beta feature**
>
> This is an open beta feature, which means you won’t see it available in your organization until you opt in. If you’re interested in joining this beta, [talk to a Redoxer](https://redoxengine.com/forms/contact-us/) to find out if you’d be a good fit. 

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)

> **Open beta feature**
>
> This is an open beta feature, which means you won’t see it available in your organization until you opt in. If you’re interested in joining this beta, [talk to a Redoxer](https://redoxengine.com/forms/contact-us/) to find out if you’d be a good fit. 

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. 
