SSO / OIDC

Overview

SSO is configured at the organization level by an Owner (the org:sso permission is owner-only). The setup involves three steps:

• Configure an OIDC provider — enter your IdP's issuer URL, client ID, client secret, and scopes
• Claim and verify email domains — prove ownership of your company's email domains via DNS-TXT records
• Enable the provider — flip the switch to start routing members to your IdP

Strata uses the @better-auth/sso plugin and supports any OIDC-compliant identity provider including Authentik, Keycloak, Okta, Azure AD, and Google Workspace.

Configuring a provider

Navigate to your organization settings and select the SSO tab. You'll need the following from your identity provider:

The client secret is encrypted before storage and decrypted just-in-time during the OIDC flow. Plaintext never rests in the database.

Domain claiming

Before SSO enforcement can take effect, you must claim the email domains your organization controls. Domain claims are globally unique — first-claim-wins, so a domain can only be claimed by one organization.

Claiming a domain

In the SSO settings, enter your domain (e.g. agency.com). The domain is normalized (IDNA/NFKC, lowercased, trailing dot stripped) and checked against a denylist of public email providers (gmail.com, outlook.com, yahoo.com, etc.).

A new claim is created with verified: false and a random verification token. The claim is inert until verified — an unverified claim has no effect on SSO routing, JIT provisioning, or password lock-out.

DNS-TXT verification

To prove you own the domain, add a DNS TXT record:

strata-verify=<your-verification-token>

The token is displayed in the SSO settings after claiming the domain. Add the TXT record to your domain's DNS configuration, then click Verify in Strata. Strata performs a live DNS TXT lookup and checks for an exact match.

On successful verification:

• The domain is marked as verified: true
• The verification token is cleared
• The SSO provider bridge is synced so the newly verified domain immediately routes to the IdP

SSO enforcement

Once a domain is verified and the OIDC provider is enabled, SSO enforcement activates for all email addresses on that domain:

• Sign-in routing — users with an SSO-enforced email are redirected to the organization's IdP when they visit the sign-in page
• Password lock-out — password sign-in is rejected at the credential boundary for SSO-enforced emails. Users must use their IdP. Existing password users are unaffected until their domain is claimed and verified.
• Signup gate — the SSO-enforced domain counts as a “claimed domain” for signup eligibility, so users on verified domains can create accounts

Exact domain matching

Strata's enforcement uses exact domain matching, not suffix matching. A claim on agency.com does not affect sub.agency.com. This is a deliberate security decision — subdomains must be claimed and verified separately.

JIT provisioning

When a user signs in through SSO for the first time, Strata automatically provisions their account:

• A user record is created (or the existing one is found) from the email in the OIDC token
• A member record is created with the member role in the domain-owning organization
• The provisioning is fully idempotent — safe to run on every login
• JIT provisioning never assigns the owner or admin role — only member. Role upgrades must be done manually by an owner.

If the email domain does not resolve to any organization (no verified claim exists), provisioning is refused and the user cannot sign in via SSO.

Provider bridge

Strata maintains two database tables for SSO: its own config table (oidc_provider) and the auth plugin's storage table (sso_provider). A bridge function syncs changes from Strata's config into the plugin's table:

• When the provider is enabled: builds the plugin's config, collects all verified domains as a comma-separated string, and upserts the plugin row
• When the provider is disabled or absent: deletes the bridged plugin row
• Any change to verified domains re-runs the bridge so sign-in routing stays current

Compatible identity providers

Strata works with any OIDC-compliant provider. Tested configurations include:

• Authentik — open-source, self-hosted
• Keycloak — open-source, self-hosted
• Okta — cloud identity platform
• Azure AD / Entra ID — Microsoft cloud
• Google Workspace — Google cloud

SAML, IdP-to-role group mapping, and SCIM provisioning are not supported. Strata is OIDC-only.

Releasing a domain

An owner can release a claimed domain from the SSO settings. This removes the claim entirely (both verified and unverified) and re-syncs the provider bridge. Users on the released domain will no longer be SSO-enforced and can sign in with password credentials.