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.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
Tell us you're starting
Create the app in your identity provider
https://app.searchable.com, and replace it in step 3.Then send us what the app gives you:Add Searchable's URLs to your app
- 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.
Verify your email domains
uk.acme.com needs its own record if people sign in with @uk.acme.com addresses.Run the test sign-in
Go live
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.Okta (OIDC)
Okta (OIDC)
- In the Okta Admin Console, go to Applications → Applications and click Create App Integration.
- Choose OIDC - OpenID Connect, then Web Application.
- Under Grant type, keep Authorization Code.
- Under Sign-in redirect URIs, enter a placeholder for now. You replace it with the redirect URI we send you (Quick setup step 3).
- Save, then assign the people (or groups) who should use Searchable.
- 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 examplehttps://acme.okta.com/oauth2/default) if you use one.
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.Okta (SAML)
Okta (SAML)
- In the Okta Admin Console, go to Applications → Applications, click Create App Integration, and choose SAML 2.0.
- 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).
- 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).
- 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.
- Sign the assertion with SHA-256.
- Add an attribute statement named
emailwith the valueuser.email(in newer Okta orgs, add it on the app’s Sign On tab with Add expression, valueuser.profile.email). - Save, assign people, and send us the app’s IdP metadata and the attribute name
email.
Microsoft Entra ID (OIDC)
Microsoft Entra ID (OIDC)
- In the Microsoft Entra admin center, go to App registrations and click New registration.
- 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).
- On Certificates & secrets, create a client secret and note its expiry date.
- On Token configuration, click Add optional claim, choose ID, and add
xms_edovandemail. Withoutxms_edov, every sign-in fails the email check, because Entra doesn’t send the standardemail_verifiedclaim. - 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.
openid email profile.Auth0 (OIDC)
Auth0 (OIDC)
- In the Auth0 Dashboard, go to Applications → Applications and click Create Application.
- Choose Regular Web Applications.
- 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.
- Send us the Client ID, the Client Secret, and the issuer: your Auth0 domain as a URL, for example
https://acme.us.auth0.com/.
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: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.
Sessions and signing out
An SSO session lasts at most 12 hours. After that, people sign in again with Continue with SSO.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.
- 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.
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.
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.
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
Troubleshooting
“We couldn't sign you in with single sign-on” straight after signing in at the identity provider
“We couldn't sign you in with single sign-on” straight after signing in at the identity provider
The test sign-in fails a check
The test sign-in fails a check
- Email verified: your identity provider didn’t say the email is verified. In Entra, add the
xms_edovoptional 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.
Sign-in fails after the identity provider, for everyone
Sign-in fails after the identity provider, for everyone
“Your workspace has no seats left”
“Your workspace has no seats left”
“Your single sign-on worked, but this account can't be used here”
“Your single sign-on worked, but this account can't be used here”
Someone isn't offered Continue with SSO
Someone isn't offered Continue with SSO
uk.acme.com isn’t covered by acme.com. The button appears only once your connection is live.Someone sees “access denied” or “not assigned”
Someone sees “access denied” or “not assigned”