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

# Single sign-on (SSO)

> Connect Okta, Microsoft Entra ID, Google Workspace or another OIDC or SAML 2.0 identity provider so your team signs in to Anam Lab with company accounts.

Single sign-on lets people sign in to [Anam Lab](https://lab.anam.ai) with their company identity provider (IdP). You connect an IdP for an email domain, prove you own the domain, and people with that email address can then sign in through your IdP and join your team.

<Info>
  Single sign-on is available on Enterprise plans. To add SSO to your agreement, [talk to our sales team](https://anam.ai/book-demo).
</Info>

## How SSO works

* **Each connection covers one email domain.** A connection links one domain, such as `example.com`, to your IdP. Subdomains such as `eu.example.com` need their own connection.
* **Domain verification comes first.** A connection stays inactive until you publish a DNS TXT record that proves you control the domain.
* **Sign-in starts in Lab.** People choose **Sign in with SSO** on the Lab sign-in page and enter their work email. Starting from your IdP's app dashboard is not supported.
* **New people join as members.** The first SSO sign-in adds the person to your team with the Member role. Owners and admins can change roles on the Team page.
* **Existing accounts are linked.** If someone already has an Anam account with that email, SSO signs them in to the same account and keeps their data.
* **SSO is optional.** People in your domain can still sign in with a password, Google or GitHub. Lab can't yet require SSO for a domain.

## Before you start

You need:

* An Anam organization on an Enterprise plan.
* The Owner or Admin role in that organization.
* Admin access to your IdP, to create an OIDC or SAML application.
* Access to your domain's DNS, to add a TXT record.

## Set up SSO

<Steps>
  <Step title="Open the SSO settings">
    In Anam Lab, open the [Team page](https://lab.anam.ai/team). You can also reach it from **Invite teammates** in the top bar. Under **Single sign-on**, choose **Add connection**.

    If you don't see **Single sign-on**, check that your organization is on an Enterprise plan and that you are an owner or admin.
  </Step>

  <Step title="Choose a protocol and enter your domain">
    Choose **OIDC** or **SAML 2.0**, whichever your IdP supports. Enter your **Email domain**, such as `example.com`.
  </Step>

  <Step title="Add Lab's settings to your IdP">
    The dialog shows the values your IdP needs under **Add to your identity provider**:

    * OIDC: the **Redirect URI**. Allow the `openid`, `email` and `profile` scopes.
    * SAML: the **ACS URL** and **Entity ID**. Your IdP must sign SAML assertions.

    Keep the dialog open while you create the application in your IdP. The values change if you close it before you add the connection.
  </Step>

  <Step title="Enter your IdP's details">
    Copy these values from your IdP into the dialog, then choose **Add connection**:

    * OIDC: the **Issuer URL**, **Client ID** and **Client secret**. Lab discovers the other endpoints from the issuer.
    * SAML: the **IdP metadata XML**. It must include the signing certificate and an HTTPS sign-in URL with the HTTP-Redirect binding.

    The connection appears with the **Pending verification** badge. Its card lists the same IdP settings for later reference. SAML connections also show a **Metadata URL** that some IdPs can import.
  </Step>

  <Step title="Verify your domain">
    Under **DNS verification**, the connection shows a TXT record. Add it with your DNS provider:

    | Field | Value                                                   |
    | ----- | ------------------------------------------------------- |
    | Type  | `TXT`                                                   |
    | Host  | `_anam-domain-verification-<connection-id>.example.com` |
    | Value | The value shown in Lab                                  |

    Some DNS providers add your domain to the host automatically. If yours does, enter only the part before your domain. After the record is published, choose **Check DNS record**.

    <Check>
      The connection changes to **Active**, and people with `@example.com` addresses can sign in with SSO.
    </Check>
  </Step>

  <Step title="Test sign-in">
    Open the [Lab sign-in page](https://lab.anam.ai/login) in a private window. Choose **Sign in with SSO**, enter your work email, and complete sign-in with your IdP. You return to Lab signed in to your organization, and the sign-in page marks SSO as your last-used method.
  </Step>
</Steps>

You can leave the TXT record in place. Lab doesn't check it again after verification.

## Configure your identity provider

These guides cover the IdP side of steps 3 and 4. Use the values from your Lab dialog wherever a guide refers to a Lab value.

<Tabs>
  <Tab title="Google Workspace (SAML)">
    1. In the [Google Admin console](https://admin.google.com), go to **Apps** > **Web and mobile apps**, then choose **Add app** > **Add custom SAML app**.
    2. Enter an app name, such as `Anam Lab`. Google rejects names with special characters such as parentheses.
    3. On **Google Identity Provider details**, choose **Download metadata**. Open the downloaded file and paste its contents into **IdP metadata XML** in Lab.
    4. On **Service provider details**, paste Lab's **ACS URL** and **Entity ID**. Leave **Signed response** unchecked. Google signs the assertion.
    5. Set **Name ID format** to `EMAIL` and **Name ID** to **Basic Information > Primary email**.
    6. Optional: on **Attribute mapping**, map **First name** to `givenName` and **Last name** to `surname` so new people get a display name. Without them, Lab uses the email address as the name.
    7. Choose **Finish**, then open **User access** and turn the app **ON** for the organizational units or groups that should use Anam.

    Google can take a few minutes to apply user access changes.
  </Tab>

  <Tab title="Microsoft Entra ID (OIDC)">
    1. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **App registrations** and choose **New registration**.
    2. Under **Redirect URI**, choose the **Web** platform and paste Lab's **Redirect URI**.
    3. After you register the app, copy the **Application (client) ID** into Lab's **Client ID**.
    4. Enter `https://login.microsoftonline.com/<tenant-id>/v2.0` as the **Issuer URL**. Your **Directory (tenant) ID** is on the app's **Overview** page.
    5. Under **Certificates & secrets**, create a client secret and paste its **Value** into Lab's **Client secret**.
    6. To limit sign-in to specific people, open the app under **Enterprise applications**, turn on **Assignment required**, and assign users or groups.

    Each person needs an email address in Entra ID that uses your connected domain.
  </Tab>

  <Tab title="Okta (OIDC)">
    1. In the Okta Admin Console, go to **Applications** > **Applications** and choose **Create App Integration**.
    2. Choose **OIDC - OpenID Connect**, then **Web Application**.
    3. Add Lab's **Redirect URI** under **Sign-in redirect URIs**, and keep the **Authorization Code** grant type.
    4. Under **Assignments**, choose who can use Anam.
    5. Copy the **Client ID** and **Client secret** into Lab.
    6. Enter your Okta domain as the **Issuer URL**, such as `https://example.okta.com`.
  </Tab>

  <Tab title="Other providers">
    Lab works with any IdP that supports OIDC or SAML 2.0.

    For OIDC, your IdP must:

    * Publish a discovery document at `<issuer>/.well-known/openid-configuration` over public HTTPS.
    * Support the authorization code flow with a client secret.
    * Return the person's email address for the `email` scope.

    For SAML, your IdP must:

    * Sign assertions. Lab doesn't support encrypted assertions.
    * Accept sign-in requests on a public HTTPS URL with the HTTP-Redirect binding.
    * Send the person's email address as the Name ID, or in an `email` attribute.

    Lab reads the optional `givenName`, `surname` and `displayName` SAML attributes for the person's name.
  </Tab>
</Tabs>

## Manage connections

Owners and admins manage connections from the menu on each connection's card.

### Rotate a client secret or signing certificate

Choose **Update credentials**. Everyone stays linked and the domain stays verified.

* **OIDC:** create a new client secret in your IdP, save it in Lab, then remove the old secret from your IdP.
* **SAML:** after your IdP publishes a new signing certificate, paste its new metadata XML. Lab shows when the current certificate expires and marks the connection **Certificate expiring** from 30 days before.

### Move to a different IdP application

A new client ID, issuer, or SAML sign-in URL belongs to a different IdP application, so it needs a new connection:

1. Add a connection for the same domain with the new application, and publish its TXT record. The old connection keeps working in the meantime.
2. Delete the old connection, then choose **Check DNS record** on the new one.

SSO sign-in is unavailable between those two actions, so do them together. People link to the new connection the next time they sign in.

### Remove someone's access

Because SSO is optional, disabling someone in your IdP only stops new SSO sign-ins. Their current Lab session continues until it expires, up to seven days after they last used it. They can also still sign in another way if they control the email address.

When someone leaves, disable them in your IdP **and** remove them from your team on the Team page.

### Delete a connection

Choose **Delete connection**. People can no longer sign in through that connection, but their current sessions stay active and they keep their accounts. They can sign in with a password using **Forgot password**.

### If your Enterprise plan ends

Connections stay saved but stop working. People sign in with a password instead, using **Forgot password** the first time. To keep SSO, [talk to our sales team](https://anam.ai/book-demo) about renewing your Enterprise agreement.

## Troubleshooting

If sign-in fails after your IdP, Lab shows an error page. Its address includes an error code, such as `error=invalid_saml_response`. Include the code and the time of the attempt when you [contact support](mailto:support@anam.ai).

<AccordionGroup>
  <Accordion title="Single sign-on doesn't appear on the Team page">
    The **Single sign-on** section is shown only to owners and admins of organizations on an Enterprise plan. Ask an owner to check your role, or [talk to our sales team](https://anam.ai/book-demo) to move to Enterprise.
  </Accordion>

  <Accordion title="We couldn't find the TXT record on example.com yet">
    Lab couldn't find the record in public DNS. Check that:

    * The host isn't duplicated, such as `_anam-domain-verification-…example.com.example.com`. If your DNS provider adds the domain, enter only the part before it.
    * The value matches Lab exactly.
    * The record is published on the same domain as the connection.

    DNS changes can take a few minutes to appear. You can check the record yourself with `dig TXT <host>`, then choose **Check DNS record** again.
  </Accordion>

  <Accordion title="The verification value expired and has been replaced">
    Verification values expire after seven days. Replace the TXT record's value with the new one shown in Lab, then choose **Check DNS record** again.
  </Accordion>

  <Accordion title="Single sign-on isn't set up for example.com">
    This appears on the sign-in page when no active connection matches the email's domain. Check that:

    * The person typed their work email address.
    * The connection shows **Active**, not **Pending verification**.
    * The email's domain exactly matches the connection. Subdomains need their own connection.
  </Accordion>

  <Accordion title="Your company's identity provider didn't allow this sign-in">
    Your IdP refused the sign-in, often because the person isn't assigned to the application. Assign them in your IdP and try again.

    In Google Workspace, the same problem shows as a Google page with `403` and `app_not_enabled_for_user`. Turn the app on for that person under **User access**.
  </Accordion>

  <Accordion title="We couldn't reach your company's identity provider">
    Lab couldn't load your OIDC provider's discovery document. Check that the connection's issuer URL is correct and publicly reachable over HTTPS, then try again.
  </Accordion>

  <Accordion title="Your company's identity provider didn't complete sign-in">
    Lab couldn't finish the OIDC sign-in with your IdP. Check that:

    * The client secret in Lab is current. Secrets in some IdPs, including Microsoft Entra ID, expire. Create a new one and save it with **Update credentials**.
    * Your IdP returns the person's email address for the `email` scope.
  </Accordion>

  <Accordion title="We couldn't verify the sign-in response from your company's identity provider">
    Lab rejected the SAML response (`invalid_saml_response`). Check that:

    * The ACS URL and Entity ID in your IdP exactly match the connection's card.
    * Your IdP signs assertions, and assertion encryption is off.
    * The Name ID is the person's email address in the connected domain.
    * The metadata in Lab is current. After a certificate rotation, use **Update credentials**.
    * The person finished signing in at your IdP within five minutes of choosing **Sign in with SSO**. Lab's sign-in request expires after that.
    * The browser didn't resend a finished sign-in, for example after going back. Start again from the Lab sign-in page.
  </Accordion>

  <Accordion title="Start single sign-on from the Lab sign-in page">
    The person opened Anam from your IdP's app dashboard (`unsolicited_response`). Lab only accepts sign-ins that start from **Sign in with SSO** on the [Lab sign-in page](https://lab.anam.ai/login). If your IdP shows Anam as an app tile, point people to the sign-in page instead.
  </Accordion>

  <Accordion title="Your organization can't add more members through single sign-on">
    Your organization has reached its member limit (`organization_full`), so people signing in with SSO for the first time can't join. Existing members can still sign in. An owner or admin can remove people who no longer need access on the Team page, or [contact support](mailto:support@anam.ai).
  </Accordion>

  <Accordion title="SAML metadata errors when adding a connection">
    * **SAML metadata must include the IdP signing certificate:** download the full metadata file from your IdP again and paste all of it.
    * **SAML metadata must provide a public HTTPS HTTP-Redirect sign-in endpoint:** your metadata needs a `SingleSignOnService` with the HTTP-Redirect binding and a public HTTPS URL.
    * **The SAML identity-provider metadata is invalid:** paste the whole XML document, starting with `<EntityDescriptor` or `<md:EntityDescriptor`.
  </Accordion>

  <Accordion title="This metadata uses a different sign-in URL">
    This appears when **Update credentials** receives metadata from a different IdP application. For OIDC, the message is **These credentials belong to another identity provider app**. Follow [Move to a different IdP application](#move-to-a-different-idp-application) instead.
  </Accordion>

  <Accordion title="Single sign-on isn't available for your organization">
    Lab rejected the sign-in (`sso_unavailable`) for one of two reasons:

    * **The organization is no longer on an Enterprise plan.** The sign-in page then shows **Single sign-on is available on the Enterprise plan**. To restore SSO, contact your account team or [talk to our sales team](https://anam.ai/book-demo).
    * **The connection was deleted while the person was signing in.** Their next attempt shows **Single sign-on isn't set up for example.com**. An owner or admin can [add the connection again](#set-up-sso).

    In both cases, people can still sign in with a password through **Forgot password**.
  </Accordion>

  <Accordion title="Everyone with access to the connection is locked out">
    Owners and admins can always sign in with a password. Choose **Forgot password** on the sign-in page, follow the emailed link, then fix or delete the connection on the Team page. If no owner or admin can sign in, [contact support](mailto:support@anam.ai).
  </Accordion>
</AccordionGroup>

## Limitations

* SSO can't be required for a domain. Password, Google and GitHub sign-in stay available.
* There is no SCIM provisioning. People join when they first sign in, and you remove them on the Team page.
* IdP roles and groups aren't mapped to Anam roles. New people join as members.
* IdP-initiated SAML sign-in, such as opening Anam from an IdP app dashboard, isn't supported.

<Card title="Add SSO to your plan" icon="building" href="https://anam.ai/book-demo">
  Single sign-on is part of Anam Enterprise. Talk to our sales team about adding it to your agreement.
</Card>