How-to guide
Add sign-in with OpenID Connect to your app
Send people to Sovrain with an authorization code request and PKCE, exchange the code and check the ID token.
This guide adds sign-in with Sovrain to a web application, using the OpenID Connect authorization code flow with PKCE. The examples use plain HTTP, so you can map them onto any OpenID Connect library.
Before you start
Ask an admin of your Sovrain organization to connect your app and to send you:
- the Discovery URL, for example
https://acme.sovrain.net/.well-known/openid-configuration; - the Client ID, and the Client secret if the Client type is CONFIDENTIAL;
- the scopes ticked under Scopes & options:
openidalways, plus any ofprofile,emailandgroups.
Also ask them to:
- add your redirect URI, for example
https://wiki.acme.example/callback, under Redirect URIs; - give at least one group access to the app, so that somebody can sign in.
Sovrain compares redirect URIs character by character, port and path included, and accepts http only for
localhost, 127.0.0.1 and [::1]. What else is refused:
Redirect URI rules.
Read the discovery document
curl https://acme.sovrain.net/.well-known/openid-configuration
Take issuer, authorization_endpoint, token_endpoint, jwks_uri, userinfo_endpoint and
end_session_endpoint from it instead of typing them into your configuration. The issuer is
https://acme.sovrain.net, with no trailing slash.
If the organization uses its own domain, the issuer and every endpoint are on that domain. Use the Discovery URL your admin gives you.
Send the person to Sovrain
For every sign-in, create a random
state, a randomnonceand a PKCEcode_verifierof 43 to 128 characters fromA-Z a-z 0-9 - . _ ~. Derive thecode_challengefrom the verifier with SHA-256 and base64url without padding:code_verifier=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n') code_challenge=$(printf '%s' "$code_verifier" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')Keep
state,nonceandcode_verifierin the person’s session in your app.Redirect the browser to the authorization endpoint with a
GETrequest (line breaks added for reading):https://acme.sovrain.net/oidc/authorize ?response_type=code &client_id=7KpZq2WmXc4RtYvBn8HdLs &redirect_uri=https%3A%2F%2Fwiki.acme.example%2Fcallback &scope=openid%20profile%20email &state=af0ifjsldkj &nonce=n-0S6_WzA2Mj &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM &code_challenge_method=S256
Sovrain accepts this request only in this shape:
GETonly, with each parameter once;response_type=codeonly, and the response always comes back in the query string. Leave outresponse_mode, or sendquery;code_challenge_method=S256only.plainis refused.
Ask only for scopes the admin ticked. If you ask for a known scope the app does not allow, for example groups,
Sovrain refuses the whole request with invalid_scope instead of leaving that scope out. Scopes Sovrain does not
know, such as offline_access, are ignored.
Handle the callback
A successful sign-in comes back as:
https://wiki.acme.example/callback?code=Zr7…&state=af0ifjsldkj&iss=https%3A%2F%2Facme.sovrain.net
- Check that
stateis the value you stored. - Check that
issis the issuer from the discovery document. - If the callback has
errorinstead ofcode, stop and show a message. Most often it isinvalid_scope(a scope the app does not allow) oraccess_denied(the app is disabled or the person denied consent). Every error and its cause: OpenID Connect › Responses.
Some problems never reach your callback. If the client_id is unknown or the redirect_uri is not registered,
Sovrain shows Sign-in request rejected and does not send the person on. A person who is in no group with access
sees No access to followed by your app’s name, on Sovrain.
Exchange the code
Exchange the code within 60 seconds. It works once, and a failed exchange spends it too.
curl https://acme.sovrain.net/oidc/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=authorization_code \
-d code="$CODE" \
--data-urlencode redirect_uri=https://wiki.acme.example/callback \
-d code_verifier="$code_verifier"
-u sends the client ID and secret in a Basic Authorization header (client_secret_basic). To send them as
client_id and client_secret form parameters instead (client_secret_post), drop -u; never send both. A public
client sends client_id as a form parameter and no secret.
The answer:
{
"access_token": "eyJ…",
"token_type": "Bearer",
"expires_in": 3600,
"id_token": "eyJ…",
"scope": "openid profile email"
}
If you get invalid_grant, the code expired or was used, the redirect_uri is not the one from the authorization
request, or the verifier does not match. Start the sign-in again. invalid_client means a wrong secret, a secret
sent by a public client, or the credentials sent twice.
Check the ID token
- Read the token header.
algmust beRS256. Find the key whosekidmatches in the document atjwks_uri. Cache the key set for up to 5 minutes and fetch it again when you meet an unknownkid; never pin a key. - Check the signature.
- Check that
issis the issuer and thataudandazpare your client ID. - Check
exp. An ID token is valid for 5 minutes. - Check that
nonceis the value you stored.
Identify the person by iss together with sub. sub is stable and is the same in every app of the organization.
iss changes if the organization later activates its own domain; sub does not. If you store iss with sub, plan
to update the stored issuer at that moment, or every person will look new to your app.
Do not identify people by email: it is present only when the address is verified, and it is always lower case.
Read more about the person
If you need the claims later, call the userinfo endpoint with the access token in the Authorization header (a token
in the query string or form body is refused):
curl https://acme.sovrain.net/oidc/userinfo -H "Authorization: Bearer $ACCESS_TOKEN"
Userinfo returns sub and the claims of the granted scopes. It does not return amr, acr or auth_time. The access
token is valid for one hour, and userinfo stops accepting it as soon as the person’s Sovrain session ends.
Variants
- If your app runs in the browser or on a device and cannot keep a secret, ask the admin to set Client type to
PUBLIC. Send no secret; PKCE is then always required. A native app needs an
httpsredirect URI or a loopback one with a fixed port. - If you want the person to sign in again, add
prompt=login, ormax_age=<seconds>to require a sign-in younger than that. Checkauth_timein the ID token. - If you want to know whether the person is already signed in without showing a page, send
prompt=noneas a normal top-level redirect. In a hidden iframe on another site it does not work: the browser does not send Sovrain’s session cookie there, so the answer is alwayslogin_required. - If you need a second step, see Require two-step sign-in from your app.
- If your app must keep working after the access token expires, see Keep users signed in with refresh tokens.
- If people may sign in on behalf of someone else, the access token is valid for 5 minutes. The ID token carries
actwith thesubof the person acting only when an admin turns on Add actor claim (OIDCact) or attribute (SAMLactor) for apps under Delegations. It is off by default, and then a delegated sign-in looks like the owner’s own. See About delegation.
Sovrain supports only the authorization code flow, so there is no implicit or hybrid flow to fall back on. What else it does not support: OpenID Connect › Not supported. All claims: Claims and attributes.