> For the complete documentation index, see [llms.txt](https://docs.rox.com/development/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rox.com/development/engineering/docs/rox-enterprise-integrations/enterprise-sso-via-auth0.md).

# Enterprise SSO via Auth0

{% hint style="info" %}
Only Enterprise organizations can use this feature.
{% endhint %}

This guide walks customer IT admins through setting up SAML SSO for Rox through Auth0 and validating how end users log in.

Once connected, your organization's users get two ways to access Rox:

* **IdP-initiated login** - Users sign in directly from their Identity Provider (e.g. Okta) and click the Rox tile from their app dashboard to land straight in the app.
* **SP-initiated login** - Users go to [run.rox.com](https://run.rox.com), enter their work email, and are automatically redirected to your IdP to authenticate before being brought into Rox.

Both flows are enabled by the same setup. Completing the wizard once unlocks both entry points for all users you've assigned in your IdP.

### Admin setup

Setting up SSO in Rox is done through a self-serve wizard powered by Auth0. Before diving in, have your IdP admin console open in a separate tab.

#### Step 1 - Start SSO setup in Rox

Go to **Rox → Settings → Organization** and click **Setup** under **Single sign-on**.

<figure><img src="/files/w7Fu6BtG5rnNdKjj8rkv" alt=""><figcaption></figcaption></figure>

#### Step 2 - Open the setup wizard

This opens the Auth0 setup wizard for SSO. Click **Get Started**.

<figure><img src="/files/gvtFa8crjuPlcgmYX66Y" alt=""><figcaption></figcaption></figure>

#### Step 3 - Choose your IdP

Choose your Identity Provider and click **Next**.

<figure><img src="/files/lPqNqQjTzZreVzDYDwa4" alt=""><figcaption></figcaption></figure>

#### Step 4 - Complete the IdP setup in the wizard

Follow the setup steps shown in the wizard. This wizard guides you through six sub-steps that move information back and forth between Rox and your IdP

**1. Create the application**

Create Rox as a new application inside your IdP.&#x20;

<figure><img src="/files/psVcuBZF3SI3uYmCnCQG" alt=""><figcaption></figcaption></figure>

Use these values:

* **App name:** `Rox`
* **Logo:** Upload the Rox logo from [rox\_symbol.svg](https://run.rox.com/rox/new/rox_symbol.svg)

**2. Paste the Single Sign-on URL and Audience URI**

Once the app is created, the wizard will show you two values, the **Single Sign-on URL** and the **Audience URI.** These tell your IdP where to send users after they authenticate, and how to identify Rox as the intended recipient.

Copy both values from the wizard and paste them into the matching fields in your IdP application.

<figure><img src="/files/3caoeeJwmjSeMNOBewoU" alt=""><figcaption></figcaption></figure>

**3. Configure attribute mapping**

Attribute mapping tells your IdP which user fields to pass to Rox during login. Without this, Rox won't receive the user's email or name, and login will fail.

Map the attributes shown in the wizard in your IdP:

* **email** → primary email field in your IdP
* **name** → full name field in your IdP

<figure><img src="/files/WBWsUpIHFHIVpVGseeXd" alt=""><figcaption></figcaption></figure>

> **Okta users:** Use these specific mappings:
>
> * `email` → `user.email`
> * `name` → `user.firstName + " " + user.lastName`

**4. Configure the connection**

Now that your IdP application is configured, you need to point the Auth0 wizard back to it. The Metadata URL is how the wizard discovers your IdP's settings automatically.

Copy the **Metadata URL** from your IdP application and paste it into the wizard under your provider configuration

<figure><img src="/files/NLG5RlbET4RJjgY4fFr3" alt=""><figcaption></figcaption></figure>

**5. Assign access**

Before the connection can be tested, your IdP needs to know which users are allowed to use it. You can scope this broadly to a group or narrowly to specific users, either works.

Assign access in your IdP application based on the wizard instructions.

<figure><img src="/files/EYghK10Pmyd1Mv3HcodL" alt=""><figcaption></figcaption></figure>

**6. Test the connection and enable it**

With everything configured, the wizard will let you run a test to confirm that the connection is working end to end. Don't skip this step, it's the only way to catch misconfigured attributes or URL mismatches before your users hit them.

Run the test in the wizard. If it passes, enable the connection to turn on SSO for your organization.

<figure><img src="/files/SfRnrAt61kuQh9uP0uAx" alt=""><figcaption></figcaption></figure>

#### Step 5 - Manage the SSO configuration later

Once the wizard completes, SSO is live for your organization. The **Setup** button in your organization settings will now show as **Reconfigure**, which you can use at any time if your IdP configuration changes or you need to update the connection.

### End-user login

Once the setup is complete, assigned users in the IdP can access Rox in two ways.  Directly from their IdP, or by starting from the Rox login page. Both flows end up in the same place.

#### 1. IdP-initiated login

The user signs in to their Identity Provider and selects the **Rox** tile.

The user is then taken directly to the Rox app.

For Okta, see the example below of how the Rox tile appears on the user's Okta home page.

<figure><img src="/files/dhFK6gnRiSImajqK0KtF" alt=""><figcaption></figcaption></figure>

#### 2. SP-initiated login

The user goes to [run.rox.com](https://run.rox.com) and enters their email address.

<figure><img src="/files/Ew8PGK3BByFFtSioQwYY" alt=""><figcaption></figcaption></figure>

After clicking **Continue**, the user is redirected to their Identity Provider login page.

<figure><img src="/files/ZjhzcbyNCDM20RgkdMcI" alt=""><figcaption></figcaption></figure>

After signing in, the user is taken directly to the Rox app.