AACSearch / guide
Single sign-on
OIDC sign-in for the console, the callback URL to register with your identity provider, requiring SSO for an organization, and where SSO ends — provisioning and authorization live elsewhere.
SSO signs people into Console. It does not replace the API keys used by applications: keys authenticate machines, SSO authenticates people.
What you can and cannot configure
Identity providers are configured per deployment by the operator, not per organization in Console. What an organization owner gets is visibility and one switch:
- see which providers are live (
OIDC,Google,GitHub); - copy the callback URL to register AACSearch as a client;
- turn Require SSO on or off.
Google and GitHub buttons appear only when the operator has set credentials for them. Native SAML is not supported — a SAML provider connects through an OIDC bridge (its own OIDC endpoint, or a broker such as Keycloak or Dex in front of it).
Register AACSearch with your identity provider
Open Settings → SSO and copy the displayed callback URL into your identity provider. It is shaped:
https://api.aacsearch.com/auth/callback/<providerId><providerId> is the deployment's configured provider id (default oidc). The
identity provider needs exactly this URL as its redirect URI.
Verify: the status badges show OIDC · on (with the provider id) once the
deployment is configured. A badge showing off means the operator has not set
the credentials yet.
Require SSO
An organization owner can enable Require SSO after a provider is configured.
Once on, password sign-in is refused for members of that organization with:
Your organization requires single sign-on. Sign in through your identity provider.Test it in a separate browser session before enabling it broadly, and keep a tested recovery process with your deployment administrator — if the provider is misconfigured, members cannot sign in with a password.
SSO does not provision or authorize
Requiring SSO changes how people authenticate. It does not create or remove membership, and it does not grant roles. Use SCIM for provisioning and organization roles for authorization.
Automatic membership by email domain
The operator can map verified email domains to organizations
(SSO_ORG_DOMAIN_MAP, e.g. {"example.com": "<organizationId>"}). A person who
signs in through the identity provider with a verified email on a mapped
domain joins that organization automatically, with the member role.
Password registration does not qualify for this mapping — only identity-provider accounts with a verified email. Confirm in Console → Team that new people arrive with the role you expect.
For deployment operators
The required configuration is SSO_OIDC_ISSUER, SSO_OIDC_CLIENT_ID and
SSO_OIDC_CLIENT_SECRET. The discovery document is read from the issuer, so the
issuer must serve standard OIDC discovery. SSO_OIDC_PROVIDER_ID defaults to
oidc. Store the client secret in deployment secrets, never in the repository.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
No provider badges, or off | The deployment has no OIDC credentials | Contact your deployment administrator |
| Identity provider rejects the redirect | Callback URL not registered exactly | Register the URL shown in Settings → SSO |
| Sign-in fails after enabling Require SSO | Provider misconfigured or unreachable | Disable Require SSO with the deployment administrator, fix, re-test |
| New SSO user has no membership | Their domain is not in the domain map, or the email is unverified | Check the mapping and the identity provider's verified-email setting |
For failures, record the time and provider name — never send client secrets or sign-in tokens to support.
Next
- SCIM provisioning — the provisioning half of the same setup.
- Console authentication — sessions, passwords and invitations.
Console authentication
Sign in to the console, recover access, choose the right credential for the job and manage your sessions.
SCIM provisioning
Synchronize organization membership from an identity provider: connect it with a SCIM token, understand what Users and Groups cover, and rotate or revoke tokens safely.