OpenID provider
Tenarium can be the sign-in service of your own applications: they redirect users to Tenarium, users sign in with their Tenarium account (password, then one-time code if enabled), approve the application, and the application receives an ID token, an access token for the Tenarium API and, if requested, a refresh token. It is a standard OpenID Connect provider (authorization code flow with PKCE), so any certified OIDC client library works.
This is different from per-tenant SSO, where Tenarium is the client of a customer's identity provider. The two combine: a user can reach Tenarium's login through your application, and the tenants' own SSO still governs who may use a password.
auth:
tokens:
enabled: true # required
issuer: "" # default users.public_url; must be the URL Tenarium is served at
provider:
enabled: true # default
session_ttl: 12h # how long the browser stays signed in at Tenarium
users:
public_url: https://login.example.com
Registering applications
Clients are managed by platform callers only (oauthclients:read|write):
curl -sX POST $API/v1/oauth-clients -H "$AUTH" -d '{
"name": "Acme Dashboard",
"redirect_uris": ["https://app.example.com/callback"],
"post_logout_redirect_uris": ["https://app.example.com/"],
"scopes": ["openid", "profile", "email", "offline_access"],
"first_party": true}'
# → {"client": {"id": "tc_...", ...}, "client_secret": "..."} the secret is shown only once
| Field | Meaning |
|---|---|
redirect_uris | 1 to 20 exact redirect URIs: https, http on loopback only (localhost, 127.0.0.1, ::1; any host with auth.sso.allow_private_issuers for development), or a private-use scheme with a dot for native apps (com.example.app:/cb). No fragments. |
post_logout_redirect_uris | where /oauth/logout may send the browser afterwards |
scopes | what the client may ask for: openid (always required in requests), profile, email, offline_access. Default openid profile email |
first_party | skip the consent screen (your own applications) |
public | no secret (single-page and mobile apps); such clients must use PKCE |
tenant_id | pin the client to one tenant: its sessions are always scoped to that tenant |
GET/PUT/DELETE /v1/oauth-clients/{client} read, replace and delete a client;
POST /v1/oauth-clients/{client}/rotate-secret issues a new secret (the old one stops working).
Changes emit oauth_client.updated and oauth_client.deleted (never with the secret hash).
The flow
-
The application redirects to
/oauth/authorize:GET /oauth/authorize?response_type=code&client_id=tc_...&redirect_uri=https://app.example.com/callback&scope=openid%20email%20offline_access&state=...&nonce=...&code_challenge=...&code_challenge_method=S256&tenant=acmecode_challenge_methodmust beS256. PKCE is mandatory for public clients and recommended for all.tenant(ID or slug) asks for a session scoped to that tenant, with the user's role there; the user must be an active member. Without it, only users with platform roles can sign in. A client withtenant_idalways uses its own tenant.prompt=loginforces the login form;prompt=nonefails withconsent_requiredinstead of showing the consent page.- Unknown clients and unregistered redirect URIs get an error page, never a redirect. Other
errors are sent to the redirect URI (
error,error_description,state).
-
Tenarium shows its login page unless the browser already has a session (an HttpOnly
tenarium_sessioncookie on/oauth, valid forauth.provider.session_ttl). The page accepts email and password, then asks for a one-time code if the user has two-factor authentication. Lockout applies, and users whose domain enforces SSO are told to use SSO; the page does not offer passkeys or SSO itself. -
For clients that are not
first_party, the user approves the requested scopes once per client; later requests for the same or fewer scopes skip the page. There is no API to list or revoke consents yet. -
The browser returns to the redirect URI with
code,stateandiss(RFC 9207). The code is valid for one minute and can be redeemed once. -
The application exchanges it at
/oauth/token:curl -sX POST https://login.example.com/oauth/token -u "tc_...:$CLIENT_SECRET" \-d grant_type=authorization_code -d code=... -d redirect_uri=https://app.example.com/callback \-d code_verifier=...# public clients send client_id=tc_... in the form instead of -u{"access_token": "...", "token_type": "Bearer", "expires_in": 900,"id_token": "...", "refresh_token": "...", "scope": "openid email offline_access"}client_secret_basicandclient_secret_postare accepted; public clients authenticate with their ID only.- The ID token is an ES256 JWT with
aud= client ID andsub,auth_time,azp,nonce(if sent),emailandemail_verified(scopeemail),name(scopeprofile) andtid(tenant sessions). - The access token is a regular Tenarium token
for the Tenarium API (
aud=auth.tokens.audience); your services can verify it the same way. - A refresh token is issued only with
offline_access. It is bound to the client it was issued to:grant_type=refresh_tokensucceeds only for that client (another client getsinvalid_grant), and rotates the token as on/v1/auth/token.
-
GET/POST /oauth/userinfowith the access token returnssub,email,email_verified,nameandtid. -
GET /oauth/logout?client_id=...&post_logout_redirect_uri=...&state=...clears the browser session and redirects only to a registered post-logout URI. It does not revoke refresh tokens already issued; usePOST /v1/auth/logoutfor that.
/oauth/login and /oauth/token share the auth.rate_limit limiter with /v1/auth/.
Discovery
With the provider enabled, /.well-known/openid-configuration advertises
authorization_endpoint, token_endpoint (/oauth/token), userinfo_endpoint,
end_session_endpoint, jwks_uri, the authorization_code and refresh_token grants, the
code response type, scopes, S256, the client authentication methods and the claims above.
All URLs are built from the issuer, so auth.tokens.issuer (default users.public_url) must be
the public base URL Tenarium is reachable at. With auth.provider.enabled: false, discovery
describes only token verification, and the /oauth endpoints are not served.