> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise SSO

> Connect your SAML 2.0 identity provider, such as Okta, Microsoft Entra ID, or Google Workspace, so people at your verified domains sign in through it.

Enterprise SSO lets people at your company sign in to Recursion through your own identity provider. They enter their work email on the sign-in screen and continue to your provider. The first time they sign in, they join your tenant as members, so there are no invitations to send. You can also require single sign-on, so people at your domains can't sign in any other way.

## Before you begin

* You need the **Admin** or **Owner** tenant role, or be the tenant's primary owner. See [Organizations and roles](/managed-agents/organizations-and-roles).
* At least one of your email domains must be verified with DNS. Single sign-on admits only addresses at your verified domains, so your identity provider can vouch for your people and nobody else's. See [Domains](/managed-agents/domains).
* Your identity provider must support SAML 2.0 and be able to send each person's email address as the NameID.
* A tenant has one identity provider connection.

## Set up single sign-on

Open the [Recursion console](https://recursion.labelbox.com), open **Settings**, and choose **Enterprise SSO**. The page walks through four steps.

<Steps>
  <Step title="Create a SAML app at your identity provider">
    The first card, **Create a SAML app at your identity provider**, shows the values your provider needs: **Single sign-on URL (ACS)**, **Audience URI (SP entity ID)**, and **SP metadata URL**. Copy them from the console into a new SAML app at your provider. Provider-specific steps are [below](#identity-provider-setup).
  </Step>

  <Step title="Check your verified domains">
    The second card lists your tenant's DNS-verified domains. If none are listed, click **Manage domains** and [verify one](/managed-agents/domains#verify-it-with-dns). You can save and test the connection before then, but you can't turn it on.
  </Step>

  <Step title="Connect your identity provider">
    In **Connect your identity provider**, choose where the settings come from:

    * **Metadata URL**: paste your provider's metadata URL into **IdP metadata URL**. Recursion reads the sign-in URL and signing certificate from it, and can refresh them later.
    * **Entered by hand**: paste the **IdP single sign-on URL** and the **Signing certificate** in PEM form, starting with `-----BEGIN CERTIFICATE-----`. The certificate is public; no key is stored.

    Leave **Turn on** unchecked for now, and click **Save connection**.
  </Step>

  <Step title="Test it">
    **Test it** shows a **Test sign-in link**. Open it in a private window and sign in at your identity provider. The link works whether single sign-on is on or off. While it's off, it signs in existing members only, so test with your own account or a test account that's already a member.
  </Step>
</Steps>

When the test works, check **Offer single sign-on at sign-in** under **Turn on**, and click **Save changes**. The status changes to **On**, and people at your verified domains can sign in through your provider.

## Identity provider setup

Use the values from the console's first card. Each provider must send the person's email address as the NameID.

<Tabs>
  <Tab title="Okta">
    1. In the Okta Admin Console, go to **Applications › Applications**, click **Create App Integration**, and choose **SAML 2.0**.
    2. Set **Single sign-on URL** to the console's **Single sign-on URL (ACS)**, and **Audience URI (SP Entity ID)** to its **Audience URI (SP entity ID)**.
    3. Set **Name ID format** to **EmailAddress** and **Application username** to **Email**.
    4. Finish creating the app, then assign the people or groups who should sign in on its **Assignments** tab.
    5. On the **Sign On** tab, copy the **Metadata URL** and paste it into **IdP metadata URL** in the console.
  </Tab>

  <Tab title="Microsoft Entra ID">
    1. In the Microsoft Entra admin center, go to **Enterprise applications**, click **New application**, then **Create your own application**, and choose **Integrate any other application you don't find in the gallery**.
    2. Open **Single sign-on** and choose **SAML**.
    3. Under **Basic SAML Configuration**, set **Identifier (Entity ID)** to the console's **Audience URI (SP entity ID)**, and **Reply URL** to its **Single sign-on URL (ACS)**.
    4. Under **Attributes & Claims**, set **Unique User Identifier (Name ID)** to `user.mail`.
    5. Assign the people or groups who should sign in under **Users and groups**.
    6. Under **SAML Certificates**, copy **App Federation Metadata Url** and paste it into **IdP metadata URL** in the console.
  </Tab>

  <Tab title="Google Workspace">
    1. In the Google Admin console, go to **Apps › Web and mobile apps**, click **Add app**, and choose **Add custom SAML app**.
    2. On **Google Identity Provider details**, copy the **SSO URL** and download the **Certificate**. Google doesn't publish a metadata URL, so in the console choose **Entered by hand** and paste the SSO URL and certificate.
    3. On **Service provider details**, set **ACS URL** to the console's **Single sign-on URL (ACS)**, and **Entity ID** to its **Audience URI (SP entity ID)**.
    4. Set **Name ID format** to **EMAIL** and **Name ID** to **Basic Information › Primary email**.
    5. Under **User access**, turn the app on for the people or organizational units who should sign in.
  </Tab>
</Tabs>

## How people sign in

* **From the sign-in screen.** A person enters their work email and clicks **Continue**. An address at one of your verified domains goes to your identity provider.
* **New people join automatically.** The first time someone signs in through your provider, they join your tenant at the domain's **Default role**, set on the [Domains](/managed-agents/domains#choose-who-can-join) card. They don't get a separate tenant of their own.
* **Existing accounts are kept.** If someone already signs in with Google or email at the same address, their first single sign-on asks them to confirm that account once. The two sign-in methods then share one account.
* **Removed members stay removed.** Someone you removed from the tenant can't rejoin through single sign-on.
* **Only verified domains.** Your provider can't sign in an address at a domain your tenant hasn't verified, whatever it asserts.

## Require single sign-on

Check **Require single sign-on for your verified domains** under **Require it**, and click **Save changes**. The connection must be on first.

While it's required, people at your verified domains can sign in only through your identity provider. Email, Google, and other sign-ins are refused for those addresses, current members included. The sign-in screen tells them to enter their work email and continue through your provider.

Your tenant's primary owner is exempt and can still sign in another way, so a broken connection can always be fixed or turned off from **Enterprise SSO**. Test the connection before you require it.

## Keep the certificate current

Identity providers rotate their signing certificates. **Enterprise SSO** shows the current certificate's expiry and warns you before it expires.

* **Metadata URL**: after your provider publishes the new certificate, click **Refresh from metadata**.
* **Entered by hand**: paste the new certificate into **Signing certificate** and click **Save changes**. Leave the field empty to keep the current one.

If the certificate expires, single sign-on fails until you replace it.

## Turn off or remove single sign-on

* **Turn off**: uncheck **Offer single sign-on at sign-in** and click **Save changes**. The connection's settings are kept, and the test link still works for existing members.
* **Remove**: click **Remove**, then **Remove single sign-on**. Members who joined through it stay, and can sign in another way.

## What can go wrong

| Symptom | Cause | Fix |
| - | - | - |
| The sign-in screen says your organization's single sign-on could not sign you in | Your identity provider's app settings don't match the console, most often the audience or entity ID. | Compare the app's ACS URL and entity ID with the console's first card, then try the test link again. |
| Sign-in fails even though the ACS URL and entity ID match | Your provider doesn't send the person's email address as the NameID. | Set the NameID to the person's email address, as in [Identity provider setup](#identity-provider-setup). |
| Your provider refuses the person before they reach Recursion | The person isn't assigned to the SAML app at your provider. | Assign them, or their group, to the app. |
| **Offer single sign-on at sign-in** can't be checked | Your tenant has no domain verified with DNS. | [Verify a domain](/managed-agents/domains#verify-it-with-dns). |
| The status shows **On, no verified domain** | Your last verified domain was removed, so the connection admits nobody. | Verify a domain again, or turn single sign-on off. |
| The metadata URL can't be read | The URL isn't public HTTPS, or the document lists no signing certificate or no HTTP-Redirect sign-in location. | Check the URL at your provider, or choose **Entered by hand** and paste the sign-in URL and certificate. |
| People at your domain can't sign in with Google or email | Single sign-on is required for your verified domains. | Sign in through your identity provider, or ask an admin to turn off **Require single sign-on for your verified domains**. |

## Next steps

<CardGroup cols={2}>
  <Card title="Domains" href="/managed-agents/domains">
    Claim and verify the domains single sign-on admits.
  </Card>

  <Card title="Organizations and roles" href="/managed-agents/organizations-and-roles">
    See what each role can do.
  </Card>
</CardGroup>