Sovrain
  1. Documentation
  2. Identity provider

Reference

OpenID Connect

Endpoints, parameters, flows, tokens, sign-out and limits of Sovrain as an OpenID Connect provider.

Sovrain is an OpenID Connect provider and OAuth 2.0 authorization server for the applications of each organization. The claims in the tokens are on Claims and attributes. The settings of an OpenID Connect application are on Application settings.

Issuer

Each organization is its own issuer:

https://acme.sovrain.net
  • No trailing slash.
  • With a primary custom domain, the issuer is that domain, for example https://login.acme.example. Requests to acme.sovrain.net are then answered with a 307 redirect to it, so applications configured with the old issuer must be updated.
  • On sovrain.net (no organization), discovery, JWKS and userinfo answer 404.

Endpoints

PathMethodsNotes
/.well-known/openid-configurationGETDiscovery document. Cache-Control: max-age=300, public. CORS.
/oidc/jwks.jsonGETPublic signing keys. Cache-Control: max-age=300, public.
/oidc/authorizeGETAuthorization endpoint. POST is not accepted.
/oidc/tokenPOSTToken endpoint. CORS.
/oidc/userinfoGET, POSTUserInfo endpoint. CORS.
/oidc/logoutGET, POSTRP-initiated logout. Shows a confirmation page.
/oidc/revokePOSTToken revocation, for Admin API tokens only. CORS.
/oidc/device_authorizationPOSTDevice authorization, for Admin API tokens only. CORS.

The CORS-enabled endpoints answer Access-Control-Allow-Origin: * without credentials. A preflight answers the methods GET,POST, Access-Control-Max-Age: 1800 and the requested headers.

Rate limits per client IP address: Limits.

Discovery document

GET https://acme.sovrain.net/.well-known/openid-configuration

{
  "issuer": "https://acme.sovrain.net",
  "authorization_endpoint": "https://acme.sovrain.net/oidc/authorize",
  "token_endpoint": "https://acme.sovrain.net/oidc/token",
  "jwks_uri": "https://acme.sovrain.net/oidc/jwks.json",
  "userinfo_endpoint": "https://acme.sovrain.net/oidc/userinfo",
  "end_session_endpoint": "https://acme.sovrain.net/oidc/logout",
  "device_authorization_endpoint": "https://acme.sovrain.net/oidc/device_authorization",
  "revocation_endpoint": "https://acme.sovrain.net/oidc/revoke",
  "scopes_supported": ["openid", "profile", "email", "groups",
    "users:read", "users:write", "users:delete", "invites:write",
    "groups:read", "groups:write", "groups:delete", "apps:read", "apps:write", "apps:delete"],
  "response_types_supported": ["code"],
  "response_modes_supported": ["query"],
  "grant_types_supported": ["authorization_code", "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "client_secret_post", "none"],
  "code_challenge_methods_supported": ["S256"],
  "authorization_response_iss_parameter_supported": true,
  "backchannel_logout_supported": true,
  "frontchannel_logout_supported": true,
  "backchannel_logout_session_supported": true,
  "frontchannel_logout_session_supported": true,
  "acr_values_supported": ["http://schemas.openid.net/pape/policies/2007/06/multi-factor",
    "https://refeds.org/profile/mfa"],
  "claims_parameter_supported": true,
  "claims_supported": ["sub", "iss", "aud", "exp", "iat", "auth_time", "nonce", "azp", "sid", "amr", "acr", "act",
    "name", "given_name", "family_name", "preferred_username", "email", "email_verified", "groups", "role"]
}

Notes on the document:

  • The device code grant, the revocation endpoint and the ten API scopes (users:read to apps:delete) work only for the built-in Admin API client cli, not for applications. See Admin API.
  • claims_parameter_supported is true, but only id_token.acr in the claims parameter has an effect.
  • Custom claims are not listed in claims_supported.
  • request_parameter_supported and request_uri_parameter_supported are absent. Sovrain ignores request and request_uri.

Signing keys

ItemValue
AlgorithmRS256 with RSA-2048 keys, for ID tokens, access tokens and logout tokens
Key setOne per organization, shared by all its OpenID Connect applications
kidThe RFC 7638 thumbprint of the key
Published in JWKSThe active key, the next key while one is staged, and a retired key for 65 minutes after it was replaced
RotationManual only: Admin › Signing keys, see Rotate signing keys. Keys do not expire.

A JWKS entry:

{
  "kty": "RSA",
  "e": "AQAB",
  "use": "sig",
  "kid": "YYeV1mfoHx9YQIh1CiB1s-TIHxnT9XlTuGLAiiEipWo",
  "alg": "RS256",
  "n": "5N8G24HgYi6AxcXxLihnnbiK…"
}

Authorization endpoint

GET https://acme.sovrain.net/oidc/authorize

Only the authorization code flow is supported, with the response in the query string.

ParameterRequiredNotes
client_idyes
redirect_uriyesMust equal a registered redirect URI exactly, character for character
response_typeyescode
scopeyesMust contain openid. Known scopes: openid, profile, email, groups. Unknown names are dropped. Every known scope requested must be registered for the client, or the whole request is refused.
staterecommendedReturned unchanged, only when sent
noncenoCopied into the ID token issued with the code
code_challengewhen the client requires PKCE43 to 128 characters
code_challenge_methodwith code_challengeS256 only
response_modenoquery only
promptnonone, login or consent. none cannot be combined with another value. Other values (select_account, create) are ignored.
max_agenoSeconds. When the sign-in is older, the person signs in again.
id_token_hintnoAn ID token Sovrain issued, expired or not. When it names someone other than the signed-in person, they sign in again. An unreadable token is ignored.
acr_valuesnoWhen it contains https://refeds.org/profile/mfa or http://schemas.openid.net/pape/policies/2007/06/multi-factor, a second step is required. Other values are ignored.
claimsnoJSON. Only id_token.acr has an effect: a second step is required when its values or value contain one of the two values listed for acr_values, or when it is {"essential":true} without values. Everything else in it is ignored.

Ignored without an error: login_hint, display, ui_locales, claims_locales, request, request_uri, resource, registration.

Responses

Success: a redirect to the registered URI with a code that is valid for 60 seconds and works once:

HTTP/1.1 302 Found
Location: https://portal.acme.example/callback?code=<44 characters>&state=af0ifjsldkj&iss=https%3A%2F%2Facme.sovrain.net

iss is always included (RFC 9207).

These errors show a page on Sovrain, Sign-in request rejected, and never redirect:

  • a parameter appears twice;
  • client_id is missing or unknown, or the application is not an OpenID Connect application;
  • redirect_uri is missing or not registered for the client.

Other errors redirect to the registered URI with error, error_description, state (when sent) and iss. They are checked in this order:

Conditionerror
response_type missinginvalid_request
response_type not codeunsupported_response_type
response_mode other than queryinvalid_request
prompt=none with another valueinvalid_request
max_age not a whole number of 0 or moreinvalid_request
claims not valid JSON, or a malformed id_token.acrinvalid_request
An essential acr that lists only values Sovrain never issuesunmet_authentication_requirements
scope without openidinvalid_scope
A requested scope not registered for the clientinvalid_scope
No code_challenge while the client requires PKCEinvalid_request
code_challenge_method missing or not S256invalid_request
code_challenge not 43 to 128 unreserved charactersinvalid_request
The application is disabledaccess_denied

What happens after the checks

In this order:

  1. With prompt=none, any step below that needs the person answers at the redirect URI: login_required (not signed in, or another person in id_token_hint), interaction_required (second step or setup needed), consent_required, or access_denied (no access).
  2. A person who is not signed in goes to the sign-in page.
  3. A person whose groups do not give access to the application sees No access to the application on Sovrain.
  4. prompt=login, an exceeded max_age or a different person in id_token_hint sends the person to sign in again. The existing session is not ended first.
  5. When the application requires two-step sign-in, or the request asks for it with acr_values or claims, a person signed in with a password only completes a second step, or sets one up.
  6. When the organization’s two-step policy requires the person to set up a second step, they do so now.
  7. A person who may sign in to the application as someone else through a delegation chooses the account.
  8. The consent page appears when the client requires consent and the person has not yet allowed all requested scopes, or with prompt=consent. Deny answers access_denied.
  9. The code is issued.

Consent is stored per client and person, with its scopes, and does not expire. Requesting more scopes asks again. The person withdraws it with Disconnect on Profile › Applications.

Redirect URI rules

The same rules apply to redirect URIs, post-logout redirect URIs and the front-channel logout URI.

RuleDetail
Absolute, with a hosthttps://portal.acme.example/callback
Schemehttps. http only for the hosts localhost, 127.0.0.1 and [::1], in every environment.
Custom schemesNot allowed (com.acme.app:/callback is refused)
FragmentNot allowed
User and password in the URINot allowed
Percent-encodingNot allowed: no % anywhere
Spaces, control characters, double quote, <, >, backslash, ^, backtick, {, vertical bar, }Not allowed
WildcardsNone. The URI is compared exactly, including path, query and port.
Loopback portsThe port must match exactly; any-port loopback (RFC 8252) is not supported
DuplicatesRefused

There is no limit on the number of URIs.

Token endpoint

POST https://acme.sovrain.net/oidc/token

The body is application/x-www-form-urlencoded. A query string answers 400 invalid_request.

Client authentication

Client typeMethod
Confidentialclient_secret_basic (HTTP Basic; id and secret are form-urlencoded before Base64, as in RFC 6749) or client_secret_post (client_id and client_secret in the body)
Publicnone: client_id in the body, no secret
  • A confidential client must have a generated secret and send it. A public client must not send one.
  • Sending both a Basic header and client_secret answers invalid_client.
  • invalid_client is 400, or 401 with WWW-Authenticate: Basic realm="oidc" when the Basic header was used.

Authorization code grant

ParameterRequiredNotes
grant_typeyesauthorization_code
codeyes
redirect_uriyesThe same value as in the authorization request
code_verifierwith PKCE

The code is refused with invalid_grant when it is unknown, expired, used, issued to another client, when redirect_uri differs, when the PKCE verifier is missing or wrong, or when the account was suspended or removed since. A code is spent even when the exchange fails.

Response 200, with Cache-Control: no-store and Pragma: no-cache:

{
  "access_token": "eyJraWQiOi…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJraWQiOi…",
  "scope": "openid profile email",
  "refresh_token": "<44 characters>"
}
  • expires_in is 300 when the person signed in as someone else through a delegation.
  • refresh_token is present only when the client allows refresh tokens.

Refresh token grant

ParameterRequiredNotes
grant_typeyesrefresh_token
refresh_tokenyes
  • Refresh tokens are off for a new client. While off, this grant answers unsupported_grant_type.
  • A refresh token works once; the response carries a new one. Presenting a used refresh token deletes every refresh token descended from the same sign-in.
  • A refresh token lives as long as the person’s Sovrain session: at most 60 days after sign-in, and it stops working when the person signs out of Sovrain or the session is ended. There is no offline access.
  • Each refresh checks again that the account is active, the session is alive, the application is enabled, the person’s groups still give access, and the session meets the application’s two-step requirement.
  • The new ID token repeats auth_time, amr and acr and has no nonce.
  • Every refusal is invalid_grant with The refresh token is invalid, expired, or already used. A refused token is spent, except one presented by another application: it stays valid for its own.

Grants not available to applications

grant_typeAnswer
missinginvalid_request
client_credentials, password, token exchange and any other valueunsupported_grant_type
urn:ietf:params:oauth:grant-type:device_codeOnly for the Admin API client cli

Errors

Errors are {"error": "…", "error_description": "…"} with fixed descriptions, for example:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}

Token lifetimes

TokenLifetime
Authorization code60 seconds, single use
ID token5 minutes
Access token1 hour; 5 minutes for a delegated sign-in
Refresh tokenUntil the Sovrain session ends, at most 60 days after sign-in
Logout token2 minutes

Access tokens are RS256 JWTs (RFC 9068, typ: at+jwt) meant for the userinfo endpoint. They cannot be revoked; the userinfo endpoint refuses them once their session has ended.

UserInfo endpoint

GET or POST https://acme.sovrain.net/oidc/userinfo

The access token is accepted only in the Authorization: Bearer header, not in the body or the query string.

Response 200, plain JSON (never signed or encrypted), with sub and the claims of the token’s scopes:

{
  "sub": "V3H7fPgwfvR2jqPjePvjHb",
  "preferred_username": "jane",
  "name": "Jane Doe",
  "given_name": "Jane",
  "family_name": "Doe",
  "email": "jane@acme.example",
  "email_verified": true
}

UserInfo never contains amr, acr, act or auth_time; read them from the ID token.

CaseAnswer
No token401, WWW-Authenticate: Bearer error="invalid_request"
Token not issued by this organization, expired, of a removed or suspended account, of an ended delegation or session, or of a deleted client401, WWW-Authenticate: Bearer error="invalid_token", Cache-Control: no-store, empty body

Sign-out

RP-initiated logout

GET or POST https://acme.sovrain.net/oidc/logout

ParameterNotes
id_token_hintAn ID token Sovrain issued; expired tokens are accepted, unreadable ones ignored
client_idMust agree with the aud of id_token_hint when both are sent
post_logout_redirect_uriMust be registered for the client exactly. An unregistered value shows an error page; it is never dropped silently.
stateAppended to the final redirect
  • Values over 2048 characters are ignored.
  • The endpoint always shows a confirmation page, Sign out?. Nothing ends until the person selects Sign out. Then Sovrain ends the Sovrain session, runs front-channel and back-channel logout for every application of that session, signs out of SAML applications that support Single Logout, and redirects.
  • Without an identified client, or for a client with sign-out turned off, the person lands on the organization’s home page.

Front-channel logout

During sign-out in the browser, Sovrain loads a hidden frame for each application with a front-channel logout URI:

https://portal.acme.example/logout/frontchannel?iss=https%3A%2F%2Facme.sovrain.net&sid=<sid>
  • At most 20 frames per sign-out.
  • Only for applications with sign-out turned on.
  • Only when the sign-out happens in the browser: the confirmation above, Sign out in the account menu, or Disconnect on Profile › Applications. Admin actions do not run front-channel logout.

Back-channel logout

Sovrain sends a logout token to each application with a back-channel logout URI:

POST /logout/backchannel HTTP/1.1
Host: portal.acme.example
Content-Type: application/x-www-form-urlencoded

logout_token=eyJraWQiOi…
ItemValue
TriggersEvery end of a Sovrain session: sign-out, a session ended in the profile, suspend or removal of the account, a password change, an admin’s reset of two-step sign-in, the end of a delegation, Disconnect, Revoke for everyone
AttemptsOne, without retries
Timeouts3 seconds to connect, 5 seconds in total
RedirectsNot followed
SuccessAny 2xx status. The result is written to the application’s activity.
Applications per sign-outAt most 20
Addresshttps on a public address; checked when saved and again when called

The claims of the logout token are on Claims and attributes.

Revocation and device authorization

/oidc/revoke and /oidc/device_authorization serve the Admin API client cli only: see Admin API. For an application’s token, /oidc/revoke answers 200 {} and does nothing.

Clients

ItemValue
TypesConfidential, public
RegistrationBy an admin, in the admin pages or the Admin API
client_id22 random characters, permanent
Client secret44 characters, shown once, stored as a SHA-256 hash. A new secret replaces the old one at once.
PKCES256. Required for public clients; required by default for confidential clients.

prompt=none in a hidden frame works only when the application and Sovrain share a site (for example app.acme.example and login.acme.example): the session cookie is SameSite=Lax, so it is not sent to a frame on another site. Use a top-level redirect.

Not supported

  • Grants: client_credentials, password, implicit, hybrid, token exchange, CIBA. The device grant is for the Admin API only.
  • Response modes: form_post, fragment. Authorization requests sent with POST.
  • Client authentication: private_key_jwt, client_secret_jwt, mutual TLS.
  • Request objects: request, request_uri (ignored), pushed authorization requests (PAR), JAR, JARM.
  • Token introspection (RFC 7662). Revoking an application’s access or refresh token through /oidc/revoke.
  • Dynamic client registration.
  • Signing algorithms other than RS256; encrypted ID tokens or userinfo responses; DPoP; certificate-bound tokens.
  • Pairwise subject identifiers; the address and phone scopes; offline_access (ignored).
  • Session Management (check_session_iframe), logout_hint, initiate_login_uri.
  • Automatic key rotation.