> ## 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 to Anam Lab, and optionally require SSO for your domains. 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. > [!NOTE] > > Single sign-on is available on Enterprise plans. To add SSO to your agreement, [talk to our sales team](https://anam.ai/get-demo). ## 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 unless you require it.** By default, people in your domain can still sign in with a password, Google or GitHub. Owners and admins can [require SSO](#require-sso) so that people in your domain sign in only through your IdP. ## 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 **1. 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. **2. 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`. **3. 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. **4. 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. **5. 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-.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**. > [!TIP] > > The connection changes to **Active**, and people with `@example.com` addresses can sign in with SSO. **6. 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. 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. > [tab] 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] 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//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] 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] Other providers > > Lab works with any IdP that supports OIDC or SAML 2.0. > > For OIDC, your IdP must: > > * Publish a discovery document at `/.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. ## Require SSO When you require SSO, people whose email address is on one of your organization's verified domains can sign in to Lab only through your IdP. Your IdP's policies, including multi-factor authentication (MFA), then apply to every Lab sign-in for those people. Lab doesn't run its own MFA and doesn't check MFA claims in your IdP's response. To require MFA for Lab, require it for the Anam application in your IdP. ### Turn on the requirement **1. Sign in with SSO** Sign out of Lab, then sign back in with **Sign in with SSO**. Lab only lets you turn on the requirement from a session that started through one of your organization's verified connections, so you know the connection works. **2. Turn on Require SSO** On the [Team page](https://lab.anam.ai/team), under **Single sign-on**, turn on **Require SSO**. The switch is available to owners and admins once a connection is **Active**. **3. Confirm the covered domains** The confirmation lists the domains the requirement covers. Choose **Require SSO**. > [!TIP] > > The **Require SSO** section says people with your domains' email addresses can only sign in through your identity provider. Any owner or admin can turn the requirement off with the same switch, however they signed in. ### What changes for people on your domains For people whose email address is on a covered domain: * They can sign in only with **Sign in with SSO**. Password, Google and GitHub sign-in are refused, and the sign-in page moves them to **Sign in with SSO** with their email filled in. * **Forgot password** is refused. A reset link sent before you turned on the requirement no longer works. * They can't change their email address or password in Lab. Nobody can change their email address to or from a covered domain. * Their existing Lab sessions that didn't start with SSO end the next time they're used. This can take up to 30 seconds after you turn on the requirement. People with other email addresses, such as contractors on their own domains, aren't affected and sign in as before. ### Which domains are covered The requirement covers the domains of your organization's active connections. Domains match exactly: a connection for `example.com` doesn't cover `eu.example.com`. If another verified connection also claims one of your domains, sign-in can't pick a connection for that domain, so the requirement doesn't apply there. The Team page lists these domains under **Require SSO**. Delete the extra connection to cover the domain. The requirement stops applying to a domain when you delete its connection, and to all your domains if your organization leaves the Enterprise plan. ### What the requirement doesn't cover * **API keys.** API keys are separate credentials and keep working. The requirement controls sign-in to Lab only. * **Existing SSO sessions.** Lab sessions last seven days and extend each day they're used. Disabling someone in your IdP doesn't end a Lab session they already have, so also remove them from your team on the Team page. * **Calls already running.** Turning on the requirement doesn't end a call in progress. * **New people when your team is full.** Once your organization reaches its member limit, someone on a covered domain who isn't yet a member can't sign in. SSO can't add them, and no other sign-in method is allowed. ### If your IdP stops working > [!WARNING] > > When SSO is required, there is no password fallback. If your IdP or the connection stops working, nobody on a covered domain can sign in, including owners and admins. Before you turn on the requirement, check that your owners and admins can sign in with SSO. If you're locked out, an owner or admin should [contact support](mailto:support@anam.ai). Support confirms the request with your account team's contact on record, then turns the requirement off. Owners and admins can then sign in with a password using **Forgot password**, fix the connection and turn the requirement back on. ## 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 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. Unless you [require SSO](#require-sso), 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 you required SSO, the requirement no longer applies to that connection's domain. ### If your Enterprise plan ends Connections stay saved but stop working, and the SSO requirement no longer applies. People sign in with a password instead, using **Forgot password** the first time. To keep SSO, [talk to our sales team](https://anam.ai/get-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). > [accordion] 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/get-demo) to move to Enterprise. > [accordion] 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 `, then choose **Check DNS record** again. > [accordion] 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] 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] 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] 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] 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] 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] 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] 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] 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 ` [accordion] 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] 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/get-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] Your organization requires single sign-on > > This appears on the sign-in page, or on an error page with the `sso_required` code, when someone on a covered domain tries a password, Google, GitHub or **Forgot password**. Choose **Sign in with SSO** on the [Lab sign-in page](https://lab.anam.ai/login) and enter your work email. See [Require SSO](#require-sso). > [accordion] Require SSO can't be turned on > > The **Require SSO** section explains why the switch is unavailable: > > * **Verify a connection to require SSO:** finish [domain verification](#set-up-sso) so a connection shows **Active**. > * **Sign out and sign back in with SSO to turn this on:** your current session didn't start with SSO. Sign out, then sign back in with **Sign in with SSO**. > * **Every verified domain is also claimed by another connection:** delete the extra connection for each domain. > [accordion] Everyone with access to the connection is locked out > > If your organization doesn't require SSO, owners and admins can 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 your organization requires SSO, or no owner or admin can sign in, [contact support](mailto:support@anam.ai). See [If your IdP stops working](#if-your-idp-stops-working). ## Limitations * Lab doesn't enforce MFA itself. Set your MFA policy in your IdP and [require SSO](#require-sso) so it applies to every sign-in. * Requiring SSO controls Lab sign-in only. API keys keep working. * 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] [Add SSO to your plan](https://anam.ai/get-demo) > > Single sign-on is part of Anam Enterprise. Talk to our sales team about adding it to your agreement. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.