Skip to main content

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.
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 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 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. 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: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).
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: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.
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).

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.
  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.
  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).
  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.
  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: 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.
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.
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.

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

Each domain shows as verified, and the test sign-in passed every check
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
If you require SSO, that teammate can no longer sign in with a password
Removing a test person from Settings → Team ends their SSO sessions for your workspace within a few minutes

Troubleshooting

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.
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.
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.
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.
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 and we’ll check what applies.
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.
That message comes from your identity provider, not Searchable. Assign them to the app there.

SCIM with Okta

Let Okta add and remove people automatically

Teams & Collaboration

Roles, permissions and inviting your team