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 toacme.sovrain.netare then answered with a307redirect to it, so applications configured with the old issuer must be updated. - On
sovrain.net(no organization), discovery, JWKS and userinfo answer404.
Endpoints
| Path | Methods | Notes |
|---|---|---|
/.well-known/openid-configuration | GET | Discovery document. Cache-Control: max-age=300, public. CORS. |
/oidc/jwks.json | GET | Public signing keys. Cache-Control: max-age=300, public. |
/oidc/authorize | GET | Authorization endpoint. POST is not accepted. |
/oidc/token | POST | Token endpoint. CORS. |
/oidc/userinfo | GET, POST | UserInfo endpoint. CORS. |
/oidc/logout | GET, POST | RP-initiated logout. Shows a confirmation page. |
/oidc/revoke | POST | Token revocation, for Admin API tokens only. CORS. |
/oidc/device_authorization | POST | Device 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:readtoapps:delete) work only for the built-in Admin API clientcli, not for applications. See Admin API. claims_parameter_supportedistrue, but onlyid_token.acrin theclaimsparameter has an effect.- Custom claims are not listed in
claims_supported. request_parameter_supportedandrequest_uri_parameter_supportedare absent. Sovrain ignoresrequestandrequest_uri.
Signing keys
| Item | Value |
|---|---|
| Algorithm | RS256 with RSA-2048 keys, for ID tokens, access tokens and logout tokens |
| Key set | One per organization, shared by all its OpenID Connect applications |
kid | The RFC 7638 thumbprint of the key |
| Published in JWKS | The active key, the next key while one is staged, and a retired key for 65 minutes after it was replaced |
| Rotation | Manual 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.
| Parameter | Required | Notes |
|---|---|---|
client_id | yes | |
redirect_uri | yes | Must equal a registered redirect URI exactly, character for character |
response_type | yes | code |
scope | yes | Must 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. |
state | recommended | Returned unchanged, only when sent |
nonce | no | Copied into the ID token issued with the code |
code_challenge | when the client requires PKCE | 43 to 128 characters |
code_challenge_method | with code_challenge | S256 only |
response_mode | no | query only |
prompt | no | none, login or consent. none cannot be combined with another value. Other values (select_account, create) are ignored. |
max_age | no | Seconds. When the sign-in is older, the person signs in again. |
id_token_hint | no | An 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_values | no | When 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. |
claims | no | JSON. 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_idis missing or unknown, or the application is not an OpenID Connect application;redirect_uriis 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:
| Condition | error |
|---|---|
response_type missing | invalid_request |
response_type not code | unsupported_response_type |
response_mode other than query | invalid_request |
prompt=none with another value | invalid_request |
max_age not a whole number of 0 or more | invalid_request |
claims not valid JSON, or a malformed id_token.acr | invalid_request |
An essential acr that lists only values Sovrain never issues | unmet_authentication_requirements |
scope without openid | invalid_scope |
| A requested scope not registered for the client | invalid_scope |
No code_challenge while the client requires PKCE | invalid_request |
code_challenge_method missing or not S256 | invalid_request |
code_challenge not 43 to 128 unreserved characters | invalid_request |
| The application is disabled | access_denied |
What happens after the checks
In this order:
- With
prompt=none, any step below that needs the person answers at the redirect URI:login_required(not signed in, or another person inid_token_hint),interaction_required(second step or setup needed),consent_required, oraccess_denied(no access). - A person who is not signed in goes to the sign-in page.
- A person whose groups do not give access to the application sees No access to the application on Sovrain.
prompt=login, an exceededmax_ageor a different person inid_token_hintsends the person to sign in again. The existing session is not ended first.- When the application requires two-step sign-in, or the request asks for it with
acr_valuesorclaims, a person signed in with a password only completes a second step, or sets one up. - When the organization’s two-step policy requires the person to set up a second step, they do so now.
- A person who may sign in to the application as someone else through a delegation chooses the account.
- The consent page appears when the client requires consent and the person has not yet allowed all requested
scopes, or with
prompt=consent. Deny answersaccess_denied. - 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.
| Rule | Detail |
|---|---|
| Absolute, with a host | https://portal.acme.example/callback |
| Scheme | https. http only for the hosts localhost, 127.0.0.1 and [::1], in every environment. |
| Custom schemes | Not allowed (com.acme.app:/callback is refused) |
| Fragment | Not allowed |
| User and password in the URI | Not allowed |
| Percent-encoding | Not allowed: no % anywhere |
Spaces, control characters, double quote, <, >, backslash, ^, backtick, {, vertical bar, } | Not allowed |
| Wildcards | None. The URI is compared exactly, including path, query and port. |
| Loopback ports | The port must match exactly; any-port loopback (RFC 8252) is not supported |
| Duplicates | Refused |
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 type | Method |
|---|---|
| Confidential | client_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) |
| Public | none: 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_secretanswersinvalid_client. invalid_clientis400, or401withWWW-Authenticate: Basic realm="oidc"when the Basic header was used.
Authorization code grant
| Parameter | Required | Notes |
|---|---|---|
grant_type | yes | authorization_code |
code | yes | |
redirect_uri | yes | The same value as in the authorization request |
code_verifier | with 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_inis 300 when the person signed in as someone else through a delegation.refresh_tokenis present only when the client allows refresh tokens.
Refresh token grant
| Parameter | Required | Notes |
|---|---|---|
grant_type | yes | refresh_token |
refresh_token | yes |
- 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,amrandacrand has nononce. - Every refusal is
invalid_grantwithThe 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_type | Answer |
|---|---|
| missing | invalid_request |
client_credentials, password, token exchange and any other value | unsupported_grant_type |
urn:ietf:params:oauth:grant-type:device_code | Only 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
| Token | Lifetime |
|---|---|
| Authorization code | 60 seconds, single use |
| ID token | 5 minutes |
| Access token | 1 hour; 5 minutes for a delegated sign-in |
| Refresh token | Until the Sovrain session ends, at most 60 days after sign-in |
| Logout token | 2 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.
| Case | Answer |
|---|---|
| No token | 401, 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 client | 401, 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
| Parameter | Notes |
|---|---|
id_token_hint | An ID token Sovrain issued; expired tokens are accepted, unreadable ones ignored |
client_id | Must agree with the aud of id_token_hint when both are sent |
post_logout_redirect_uri | Must be registered for the client exactly. An unregistered value shows an error page; it is never dropped silently. |
state | Appended 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…
| Item | Value |
|---|---|
| Triggers | Every 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 |
| Attempts | One, without retries |
| Timeouts | 3 seconds to connect, 5 seconds in total |
| Redirects | Not followed |
| Success | Any 2xx status. The result is written to the application’s activity. |
| Applications per sign-out | At most 20 |
| Address | https 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
| Item | Value |
|---|---|
| Types | Confidential, public |
| Registration | By an admin, in the admin pages or the Admin API |
client_id | 22 random characters, permanent |
| Client secret | 44 characters, shown once, stored as a SHA-256 hash. A new secret replaces the old one at once. |
| PKCE | S256. 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 withPOST. - 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
addressandphonescopes;offline_access(ignored). - Session Management (
check_session_iframe),logout_hint,initiate_login_uri. - Automatic key rotation.