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

# Set Up Single Sign-On (SSO) for Searchable

> Let your team sign in to Searchable through Okta, Microsoft Entra ID or Auth0, and require it for your company's email domains

## Overview

Single sign-on (SSO) lets people at your company sign in to Searchable with their work account at your identity provider, instead of a Searchable password. Once SSO is live, anyone with an address on your verified email domains can sign in with **Continue with SSO**, and the first time they do, Searchable creates their account and adds them to your workspace.

You can also **require** SSO, so people on your domains can't sign in with a password, a magic link or Google.

| Identity provider | Protocol |
| - | - |
| Okta | OIDC or SAML |
| Microsoft Entra ID | OIDC |
| Auth0 | OIDC |

> [!NOTE]
>
> SSO is set up together with the Searchable team. You create an app in your identity provider and
> publish a DNS record; we create your connection, check your domains, and take it live once a test
> sign-in passes. Contact [support@searchable.com](mailto:support@searchable.com) to get started.

Each workspace has one SSO connection, which can cover several email domains.

## Prerequisites

* You're an admin at your identity provider who can create app integrations and assign people to them.
* You can add TXT records to the DNS of each email domain your team signs in with (for example `acme.com`).
* Someone with an address on one of those domains who can run the test sign-in.

## Quick setup

**1. Tell us you're starting**

Email [support@searchable.com](mailto:support@searchable.com) and tell us your identity provider, whether you want OIDC or SAML (Okta only), and the email domains your team uses.

**2. Create the app in your identity provider**

Follow the steps for your provider in [Create the app in your identity provider](#create-the-app-in-your-identity-provider). We can only give you Searchable's redirect URI (OIDC) or ACS URL and entity ID (SAML) once your connection exists. If your provider asks for them when you create the app, enter a placeholder for now, such as `https://app.searchable.com`, and replace it in step 3.

Then send us what the app gives you:

| Protocol | What you send us |
| - | - |
| OIDC | The **issuer URL**, the **client ID**, the **client secret**, and the date the client secret **expires** |
| SAML | The app's **IdP metadata XML** (it carries the sign-in URL and the signing certificate), and the name of the **email attribute** |

Send the client secret through a secure channel, not in plain email. We need its expiry date so we can warn you before it runs out (see [Before a secret or certificate expires](#before-a-secret-or-certificate-expires)).

**3. Add Searchable's URLs to your app**

We create your connection and send you its URLs. Replace the placeholder in your app with exactly what we send:

* **OIDC:** the **redirect URI**, which looks like `https://app.searchable.com/api/auth/sso/callback/<connection id>`.
* **SAML:** the **ACS URL** (`https://app.searchable.com/api/auth/sso/saml/acs/<connection id>`) and the **entity ID** (`https://app.searchable.com/api/auth/sso/saml/<connection id>`), and an SP metadata file if your provider can import one.

**4. Verify your email domains**

For each domain, we send you a TXT record to publish:

| Record type | Name | Value |
| - | - | - |
| TXT | `_searchable-verify.acme.com` | `sv=` followed by a token we send you |

Publish the value exactly as we send it, then tell us. We look the record up on public DNS resolvers, so we can **check again** as soon as your DNS provider has published it. You can leave the record in place afterwards.

A subdomain is separate: `uk.acme.com` needs its own record if people sign in with `@uk.acme.com` addresses.

**5. Run the test sign-in**

We send you a test link, valid for 7 days. Someone at your company whose address is on a verified domain opens it and signs in at your identity provider. The test only checks the sign-in: it doesn't create an account, add anyone to your workspace, or sign anyone in to Searchable.

We see a report of every check and tell you if anything needs fixing. See [What the test checks](#what-the-test-checks).

**6. Go live**

Once a domain is verified and the latest test sign-in passed every check, we take your connection live. From then on, people on your verified domains see **Continue with SSO** on the Searchable login page.

Tell us whether to **require** SSO for your domains (see [Requiring SSO](#requiring-sso)).

## Create the app in your identity provider

Your app needs to let people sign in to Searchable with their email address. Searchable reads the email from the sign-in, and only accepts addresses on your verified domains.

> [accordion] Okta (OIDC)
>
> 1. In the Okta Admin Console, go to **Applications → Applications** and click **Create App Integration**.
> 2. Choose **OIDC - OpenID Connect**, then **Web Application**.
> 3. Under **Grant type**, keep **Authorization Code**.
> 4. Under **Sign-in redirect URIs**, enter a placeholder for now. You replace it with the redirect URI we send you (Quick setup step 3).
> 5. Save, then assign the people (or groups) who should use Searchable.
> 6. Send us the **client ID**, the **client secret**, and your **issuer URL**: your Okta domain (for example `https://acme.okta.com`), or your authorization server's issuer (for example `https://acme.okta.com/oauth2/default`) if you use one.
>
> Searchable asks for the scopes `openid email profile`.
>
> If you use an authorization server (an issuer containing `/oauth2/`), its **Access Policies** must have a rule that covers this app and the **Authorization Code** grant. The default policy usually has one; if none matches, Okta signs the person in and then refuses to complete sign-in.

> [accordion] Okta (SAML)
>
> 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 a placeholder for now, and tick **Use this for Recipient URL and Destination URL**. You replace it with the ACS URL we send you (Quick setup step 3).
> 3. Set **Audience URI (SP Entity ID)** to a placeholder for now. You replace it with the entity ID we send you (Quick setup step 3).
> 4. Set **Name ID format** to **Persistent**, and choose an **Application username** that never changes for a person. Searchable recognises a returning person by their Name ID, so a Name ID that follows their email breaks sign-in when their email changes.
> 5. Sign the assertion with **SHA-256**.
> 6. Add an attribute statement named `email` with the value `user.email` (in newer Okta orgs, add it on the app's **Sign On** tab with **Add expression**, value `user.profile.email`).
> 7. Save, assign people, and send us the app's **IdP metadata** and the attribute name `email`.
>
> Searchable reads the email only from that attribute, so make sure people can't edit their own email in Okta (**Profile Editor**).

> [accordion] Microsoft Entra ID (OIDC)
>
> 1. In the Microsoft Entra admin center, go to **App registrations** and click **New registration**.
> 2. Under **Redirect URI**, choose **Web** and enter a placeholder for now. You replace it with the redirect URI we send you (Quick setup step 3).
> 3. On **Certificates & secrets**, create a **client secret** and note its expiry date.
> 4. On **Token configuration**, click **Add optional claim**, choose **ID**, and add `xms_edov` and `email`. Without `xms_edov`, every sign-in fails the email check, because Entra doesn't send the standard `email_verified` claim.
> 5. Send us the **Application (client) ID**, the client secret and its expiry date, and the issuer `https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0`.
>
> Searchable asks for the scopes `openid email profile`.

> [accordion] Auth0 (OIDC)
>
> 1. In the Auth0 Dashboard, go to **Applications → Applications** and click **Create Application**.
> 2. Choose **Regular Web Applications**.
> 3. On the **Settings** tab, leave **Allowed Callback URLs** for now. Add the redirect URI we send you there in Quick setup step 3, and save.
> 4. Send us the **Client ID**, the **Client Secret**, and the issuer: your Auth0 domain as a URL, for example `https://acme.us.auth0.com/`.
>
> Searchable asks for the scopes `openid email profile`. Auth0 must report each person's email as verified, so people whose email Auth0 hasn't verified can't sign in.

## What the test checks

The test sign-in runs every check a real sign-in runs, and reports each one by name:

| Check | What it means |
| - | - |
| Signature | The sign-in was signed by your identity provider's key or certificate. |
| Issuer, audience | It came from the issuer we have on file, and was meant for Searchable's app. |
| Expiry | It hasn't expired. |
| Required claims | It includes the person's email and a permanent ID. |
| Email verified (OIDC) | Your identity provider says the email is verified (`email_verified`, or `xms_edov` for Entra). |
| Email attribute (SAML) | The email attribute you named arrived, with one address in it. |
| Email domain | The email is on one of your verified domains. |

Going live needs a test that passed every check. If we change the connection before it goes live (a new client secret or new SAML metadata), it needs a new passing test.

## Signing in

On the Searchable login page, people type their work email. For an address on your verified domains, the page shows **Continue with SSO**, which sends them to your identity provider and back.

Sign-in has to start from Searchable's login page. Opening Searchable from your identity provider's app dashboard doesn't sign people in.

### Who can join

The first time someone signs in with SSO, Searchable finds their existing account by email, or creates one, and adds them to your workspace:

* **Only addresses on your verified domains** can sign in with SSO. People on other domains (a contractor's own address, say) sign in the usual way, with an invitation.
* **Someone you invited** joins with the invitation's role and projects. Their SSO sign-in accepts the invitation.
* **Anyone else on your domains** joins with your connection's default role and access to every project. Tell us which default role you want: Admin, Member or Viewer.
* **If your workspace has no seats left**, they can't join, and your owner and admins get an email (at most once a day per person).
* **An existing account whose email was never verified** (for example, a password sign-up nobody confirmed) is taken over by the first SSO sign-in: its password and Google sign-in are removed, it's signed out everywhere, and the API keys it created are revoked in every workspace, along with its connected MCP apps. A teammate's integration built on one of those keys stops working. An account whose email was verified is simply linked, and keeps what it has.

> [!NOTE]
>
> Your identity provider decides who can sign in. Someone not assigned to the app is turned away at
> your identity provider's own sign-in page, and never reaches Searchable.

### Sessions and signing out

An SSO session lasts at most **12 hours**. After that, people sign in again with **Continue with SSO**.

> [!NOTE]
>
> **Signing out with SSO.** Signing out of Searchable ends your Searchable session only. It doesn't
> sign you out of your identity provider (Okta, Microsoft Entra ID, Auth0), so while you're still
> signed in there, **Continue with SSO** signs you straight back in without asking for your password.
> To end both, sign out of your identity provider too. Signing out of your identity provider doesn't
> end an open Searchable session either; an SSO session ends on its own within 12 hours.

## Requiring SSO

With **Require SSO** on, people on your verified domains can sign in to Searchable only with SSO. Searchable refuses every other way in for those addresses, with the message "Your company requires single sign-on for this address":

* password sign-in and sign-up, magic links and email codes, Google sign-in, and password resets;
* the workspace owner too: there's no exception.

Nothing is deleted. Accounts, passwords and workspaces stay as they are, so if Require SSO is turned off later, people can use their old password again without a reset.

* **People already signed in another way** stay signed in until that session expires; it isn't renewed.
* **People on other domains**, such as contractors you invited, aren't affected.
* **API keys and connected integrations** keep working: they aren't sign-ins.
* **Invitations** to addresses on your domains tell the person to sign in with their company account, and their first SSO sign-in accepts the invitation.

If your identity provider breaks and your team is locked out, contact us: we can turn Require SSO off while you fix it, and back on afterwards. Your owner and admins are emailed each time it's turned off or on.

## Removing people

* **Remove someone from your workspace** (in **Settings → Team**) and their SSO sessions for your workspace end within a few minutes. A session they started another way (a password, a magic link or Google) runs to its own expiry, but it no longer opens your workspace.
* **Also remove them at your identity provider.** While someone on your verified domains is still assigned to the app, they can sign in with SSO again and rejoin your workspace.

To have Okta add and remove people automatically, see [SCIM with Okta](https://docs.searchable.com/advanced/okta-scim.md).

### Turning SSO off

If you ask us to turn SSO off:

* Everyone keeps their account, workspace and data. Your domains are released, so their addresses go back to the normal login.
* People who had no Searchable password get an email telling them how to sign in with a magic link or set a password.
* Open SSO sessions run out within 12 hours. If you can't trust your identity provider any more, ask us to end them straight away.
* Any SCIM tokens stop working.

If you turn it back on later, your domains need checking again and a new test sign-in before it goes live.

## Before a secret or certificate expires

When your OIDC client secret expires, nobody can sign in with SSO until it's replaced. A SAML signing certificate that expires keeps working, because Searchable pins the certificate itself, but replace it anyway so your identity provider can keep signing with a current one.

Searchable emails your workspace owner and admins as the expiry gets close: one email when it's 30 days away, one at 7 days and one at 1 day. If we first notice it closer to the date, you get only the nearest of those. No email is sent for a SAML certificate whose replacement is already in place.

To replace it with no downtime:

* **OIDC:** create a new client secret at your identity provider and send it to us with its expiry date. Keep the old one in place until we confirm the switch.
* **SAML:** create the new certificate at your identity provider and send us the metadata that carries it, before you start signing with it. Searchable then accepts both the old and the new certificate, so you can switch without downtime.

## Verify your setup

> [!TIP]
>
> Each domain shows as verified, and the test sign-in passed every check

> [!TIP]
>
> After go-live, a teammate on your domain sees **Continue with SSO** on the login page and lands in your workspace with the expected role

> [!TIP]
>
> If you require SSO, that teammate can no longer sign in with a password

> [!TIP]
>
> Removing a test person from **Settings → Team** ends their SSO sessions for your workspace within a few minutes

## Troubleshooting

> [accordion] “We couldn't sign you in with single sign-on” straight after signing in at the identity provider
>
> The most common cause is a sign-in that didn't start from Searchable: opening Searchable from your identity provider's app dashboard, going back to an old sign-in tab, or reusing a sign-in link. Each sign-in works once, for one browser. Go to Searchable's login page, enter your email and click **Continue with SSO** again, in a single tab.

> [accordion] The test sign-in fails a check
>
> We send you the failed checks. The usual causes:
>
> * **Email verified:** your identity provider didn't say the email is verified. In Entra, add the `xms_edov` optional claim. In Auth0, the person's email must be verified there.
> * **Email domain:** the tester's email isn't on a verified domain. Check the domain's TXT record has verified, and that the tester signs in with an address on it (not a subdomain or another domain).
> * **Email attribute (SAML):** the attribute name you sent us doesn't match what your app sends. Names must match exactly, including case.

> [accordion] Sign-in fails after the identity provider, for everyone
>
> Your identity provider refused to complete the sign-in. Check that the client secret hasn't expired or been replaced; if it has, send us the new one. For Okta with an authorization server, check its **Access Policies** have a rule for this app and the Authorization Code grant.

> [accordion] “Your workspace has no seats left”
>
> The identity provider vouched for the person, but your workspace is full. Your owner and admins get an email about it. Free up or add a seat, then ask the person to sign in again.

> [accordion] “Your single sign-on worked, but this account can't be used here”
>
> The sign-in itself worked, but the Searchable account for that email can't join your workspace: for example, it's been suspended, or it belongs to an account managed elsewhere. Contact [support@searchable.com](mailto:support@searchable.com) and we'll check what applies.

> [accordion] Someone isn't offered Continue with SSO
>
> Check their address is on a verified domain, exactly: `uk.acme.com` isn't covered by `acme.com`. The button appears only once your connection is live.

> [accordion] Someone sees “access denied” or “not assigned”
>
> That message comes from your identity provider, not Searchable. Assign them to the app there.

## Related

> [card] [SCIM with Okta](https://docs.searchable.com/advanced/okta-scim.md)
>
> Let Okta add and remove people automatically

> [card] [Teams & Collaboration](https://docs.searchable.com/advanced/teams-collaboration.md)
>
> Roles, permissions and inviting your team


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.