How-to guide
Keep users signed in with refresh tokens
Renew access tokens without sending the person back to Sovrain, and handle rotation and the end of the session.
This guide lets your app get new access and ID tokens while the person stays signed in to Sovrain, without a browser redirect.
Before you start
- Sign-in with OpenID Connect works in your app. See Add sign-in with OpenID Connect to your app.
- Ask an admin to turn on Allow refresh tokens under Scopes & options of your app. It is off by default, and without it Sovrain issues no refresh tokens.
Get and use a refresh token
Sign the person in as usual. The token response now also contains
refresh_token. You do not need to ask foroffline_access; Sovrain ignores that scope.Store the refresh token on your server, next to the person’s session in your app.
Before the access token expires, ask for new tokens. Use
expires_infrom the last response: 3600 seconds normally, 300 seconds when someone signed in on behalf of another person.curl https://acme.sovrain.net/oidc/token \ -u "$CLIENT_ID:$CLIENT_SECRET" \ -d grant_type=refresh_token \ -d refresh_token="$REFRESH_TOKEN"A public client sends
-d client_id=$CLIENT_IDinstead of-u.Replace the stored refresh token with the new
refresh_tokenfrom every response. Each refresh token works once.Use the new ID token if you need fresh claims. It repeats
auth_time, andamrandacras the session has them: if the person adds their first second step in this session, a refreshed token shows it. It has nononce, so do not check the nonce on a refreshed ID token. Group and profile claims are read again at each refresh.If the answer is
invalid_grant(“The refresh token is invalid, expired, or already used.”), drop the person’s session in your app and send them to sign in again.
Plan for these rules
- Refresh one at a time. If a used refresh token is presented again, Sovrain deletes every refresh token of that sign-in, with no grace period. Two requests racing with the same token sign the person out of your app. Serialize refreshes per session.
- A refresh token never outlives the Sovrain session. It stops working when the person signs out of Sovrain or ends that session from their profile, they change their password in another session, they are suspended or removed, they select Disconnect for your app in their profile, an admin selects Revoke for everyone on your app, or the session reaches its limit of 60 days. There is no offline access.
- Every refresh checks access again. It is refused when the account is no longer active, the app is disabled, the person is no longer in a group with access, the app requires two-step sign-in and the session has no second step, or the organization’s deadline for setting up two-step sign-in has passed and the person has not set it up. A refused refresh spends the token.
- Sovrain cannot revoke your refresh tokens on request. The revocation endpoint answers
200to an app’s token and does nothing. To drop one, delete it from your storage. To end the person’s Sovrain session as well, sign them out.
If refresh tokens are turned off for your app, a refresh request gets unsupported_grant_type.
Why refresh tokens are tied to the session: About sessions and sign-out. Token lifetimes: Limits.