Single sign-on
By default, people sign in to Search2o with an email and a password. With single sign-on they sign in through your company's identity provider instead: Microsoft Entra ID, Okta, Google Workspace, or any provider that speaks OpenID Connect. The identity provider checks who the person is. Search2o still decides everything else: whether the person is a member of your account, which role the person has, and how long the session lasts.
Password sign-in and single sign-on can be used together. An account keeps its password sign-in while single sign-on is set up and proven. After that, an administrator can turn password sign-in off so that single sign-on is the only way in, or leave both on for good. Single sign-on is configured on the Admin › Authentication page.
Before you start
- An account at your identity provider where you can register an application. Registering the application is an administrator task at the provider.
- The address your users open Search2o at, such as
https://search2o.example.com/ui. You register this address at the provider and enter the same address in Search2o. The two must match exactly.
Step 1: register an application at your identity provider
At your identity provider, create a new application. Providers call it an app registration, a client, or an application integration. Set the application up as a web application that uses the authorization code flow. When the provider asks for a redirect URI, also called a callback or sign-in return URL, enter your Search2o address, the same one your users open:
https://search2o.example.com/uiThe provider then gives you a client ID and a client secret. Please copy both before you leave the page; most providers show the secret only once. You also need the provider's issuer URL, the base address the provider publishes its configuration under. The exact form differs by provider; see the notes below.
Step 2: enter the details in Search2o
On the Admin › Authentication page, choose OpenID Connect as the single sign-on method and fill in the settings. The issuer is all Search2o needs to find the provider: everything else about the provider is read from <issuer>/.well-known/openid-configuration. The default scopes, claims and verified-email rule suit almost every provider.
| Field | Type | Default | Description |
|---|---|---|---|
method | "oidc" | "oidc" | Identifies which sign-in method this is. |
issuerrequired | string | The provider's issuer URL, such as https://login.example.com. Its configuration is read from there, and it is what the 'iss' claim must match. | |
clientIdrequired | string | The client id this account was registered with at the provider. | |
returnUrlrequired | string | Where the identity provider sends the browser after signing in: the Search2o UI as it is reached from a browser, such as https://search2o.example.com/ui. Register this same address at the provider as the application's redirect URI - the two must match exactly, or the provider refuses the sign-in. One address for the account. | |
clientSecret | string | The client secret the provider issued for this registration. Search2o Cloud uses it to exchange a sign-in code for tokens; it is encrypted at rest and never returned. Leave it empty on an update to keep the stored one. | |
scopes | list of string | ['openid', 'profile', 'email'] | What to ask the provider for. The email and name are read from the result, so both are needed. |
requireVerifiedEmail | boolean | true | Whether the provider must say the email address is verified. Leave it on unless your provider never sends that claim. |
emailClaim | string | "email" | Which claim in the token holds the email address. |
nameClaim | string | "name" | Which claim in the token holds the person's name. |
provisioning | "reject" | "createUser" | "reject" | What to do when somebody signs in and has no account here. |
allowedEmailDomains | list of string | Only addresses in these domains may sign in. Leave it empty to allow any address the provider vouches for. |
The client secret is stored encrypted and is never returned, so the settings page shows the field blank once the secret is saved. To replace the secret, type a new one. To change any other setting, leave the field blank and the stored secret is kept.
Step 3: test it, then decide about passwords
Keep password sign-in on while you test. Save the settings, then open Search2o in a new browser session: the sign-in dialog offers single sign-on beside the password form. Sign in through your provider and confirm that you arrive in Search2o as the right person.
Once that works, decide whether to turn password sign-in off.
- Leave it on to let people use either method. This helps during a rollout, and it is necessary for anyone who is not in your identity provider, such as an outside contractor.
- Turn it off so that single sign-on is the only way in. Search2o refuses to turn password sign-in off until single sign-on is configured, so that an account always keeps a way to sign in. Once it is off, a person can sign in only while your provider is available, so we would suggest turning it off only once single sign-on is proven.
Per-provider notes
The settings that differ by provider are the issuer and, occasionally, the email claim.
- Microsoft Entra ID. The issuer is
https://login.microsoftonline.com/<tenant-id>/v2.0, with your tenant's id and the/v2.0on the end. Entra does not always sendemail; if sign-ins are refused for a missing email, set the email claim topreferred_username. Register the redirect URI under the Web platform. - Okta. The issuer is
https://<your-org>.okta.com, orhttps://<your-org>.okta.com/oauth2/defaultif you use the default authorization server. Create an OIDC web application and enable the authorization code grant. - Google Workspace. The issuer is
https://accounts.google.com. Create an OAuth client of type Web application in the Google Cloud console.
Any other OpenID Connect provider works the same way: register a web application with your Search2o address as the redirect URI, and give Search2o the issuer, the client ID and the client secret.
What your users see
A person opening Search2o is sent to your identity provider to sign in, and comes straight back signed in, without typing a Search2o password. When both sign-in methods are on, the person is offered the choice.
Roles and membership
The identity provider says only who the person is. The person's role is set in Search2o, as it always has been, and signing in through the provider changes nobody's role. A user created automatically by the Create user setting starts with the user role; an administrator promotes the user from the Users page.
Removing people
Search2o and your identity provider are separate. Disabling a person at the identity provider stops the person from starting a new Search2o session; sessions the person already has continue, and the person's integration tokens stay valid. When someone leaves, please remove the person in Search2o as well, from the Users page.
Signing out of Search2o ends the Search2o session only. The person stays signed in at your identity provider.
What Search2o stores, and where the secret lives
For each user, Search2o stores the identity provider's permanent id for that person together with the issuer, so the same email address can never be quietly reassigned to a different person. The client secret is encrypted before it is written and is never sent back out. The exchange with your identity provider happens in Search2o Cloud; your agent server never holds the secret and never talks to the provider.