Managing your users’ sessions
GOV.UK One Login’s session timeout duration is 1 hour. The 1 hour timeout starts when your user last interacts with GOV.UK One Login, not 1 hour from when they start their journey. You have different methods to manage a user’s session depending on the session timeout duration of your service. If this duration is:
- less than 1 hour: there’s guidance on managing your users’ sessions if using a session expiry below 1 hour
- 1 hour: both your session and GOV.UK One Login’s expire after 1 hour and you send a request to the
/logout endpointto log your users out - more than 1 hour: GOV.UK One Login’s session will expire before your session, so your user has to reauthenticate themselves if they need to log in to another service after this time
Managing user sessions if your service session is less than 1 hour
We advise that your service has either the same or a longer session expiry than GOV.UK One Login.
If your service has a session expiry shorter than 1 hour and your user’s session in your service has expired, GOV.UK One Login will automatically log your user back in if they return to your service. Your user will not have to re-enter their username and password and there is no disruption to their journey. This also applies if your user is using another service integrated with GOV.UK One Login.
Build functionality to log your user out
You must do this because the GOV.UK One Login session cookie is persistent and remains valid even if the device or browser is closed. If your users share devices, for example in a workplace or family laptop, there could be a risk of users accidentally sharing sessions if they cannot log themselves out.
You have different options to build functionality to log your users out:
- use the GOV.UK One Login service header which contains a built-in Sign out button
- if your application ends in a user selecting Submit, code the submit button to automatically log the user out
- build an auto-logout after a period of inactivity from a user
- include a logout button
All of these options must send a logout query to the /logout endpoint to end the user’s session.
Log your user out of GOV.UK One Login
To log users out of GOV.UK One Login, you need to call the /logout endpoint.
You can also request logout notifications from GOV.UK One Login.
Make a request to ‘Log your user out of GOV.UK One Login’
You must set up the functionality to log users out of a GOV.UK One Login session.
- Log your user out of using your application - the way you do this will depend on how you have built your service.
In the user’s browser, make a
GETrequest to GOV.UK One Login’s/logoutendpoint to end your user’s session.HTTP/1.1 GET Location: oidc.integration.account.gov.uk? id_token_hint=eyJraWQiOiIxZTlnZGs3I... &post_logout_redirect_uri=http://example-service.com/my-logout-url &state=sadk8d4--lda%d
- a continuous line of text separating each parameter with an ampersand (&)
- not split across multiple lines
- without any additional separators such as newline, commas or tabs
| Parameter | Required, recommended or optional | Description |
|---|---|---|
id_token_hint |
Recommended - however, if you use post_logout_redirect_uri, this parameter is required |
This is the ID token GOV.UK One Login previously issued when you made a request to the /token endpoint for your user’s current session. |
post_logout_redirect_uri |
Optional - however, if you do not specify this parameter, the endpoint redirects your user to the default logout page for GOV.UK One Login | You can only use this parameter if you have specified an id_token_hint.This parameter is the URL you want to redirect your users to after you have logged them out. The post_logout_redirect_uri must match the logout URI you specified when you registered your service to use GOV.UK One Login. |
state |
Optional | You can use this query parameter to maintain state between the logout request and your user being redirected to the post_logout_redirect_uri. |
Receive response for ‘Log your user out of GOV.UK One Login’
After you have made your GET request to GOV.UK One Login’s /logout endpoint, you should receive a response similar to this:
HTTP 1.1 302 Found
Location: https://example-service.com/my-logout-url&state=sadk8d4--lda%d
You have now logged your user out of GOV.UK One Login and terminated all their sessions.
Request logout notifications from GOV.UK One Login
GOV.UK One Login can use a POST request to notify you when a user who has previously logged into your service using GOV.UK One Login has logged out.
These notifications are optional, but we recommend supporting them, otherwise your service will not know if your user has logged out.
You can request to receive logout notifications by providing a back_channel_logout_uri when you register your service to use GOV.UK One Login.
You can only supply one back_channel_logout_uri per client.
When you receive a logout notification for an end user, you must close all the sessions you hold for that user in your service.
The logout notifications follow the OIDC back-channel logout specification.
There’s an example implementation of handling a back-channel logout notification.
You must make sure your back_channel_logout_uri can accept POST requests with a Content-Type of application/x-www-form-urlencoded from GOV.UK One Login.
The back_channel_logout_uri must be available using the internet. Using localhost will not work.
GOV.UK One Login will send a POST request to your back_channel_logout_uri when a user who has logged into your service using GOV.UK One Login has logged out. The POST body will contain a logout_token, which will be a signed JSON web token (JWT).
Here’s an example of a decoded back-channel logout token:
{
"kid": "644af598b780f54106c2465489765230c4f8373f35f32e18e3e40cc7acff6",
"alg": "ES256"
}.{
"iss": "https://oidc.integration.account.gov.uk/",
"sub": "urn:fdc:gov.uk:2022:56P4CMsGh_02YOlWpd8PAOI-2sVlB2nsNU7mcLZYhYw=",
"aud": "YOUR_CLIENT_ID",
"iat": 1713185467,
"exp": 1713185587,
"jti": "30642c87-6167-413f-8ace-f1643c59e398",
"events": {
"http://schemas.openid.net/event/backchannel-logout": {}
}
}
As an end user might have multiple sessions with your service, you may receive multiple logout notifications for the same user.
Validate your logout token
Once you’ve received a POST request to your back_channel_logout_uri, you must validate the JWT signature and logout token payload.
- Validate that the JWT
kidclaim in the logout token header exists in the JWKS (JSON web key set) returned by the/jwksendpoint. - Check the JWT
algheader matches the value for the key you are using. - Use the key to validate the signature on the logout token according to the JSON Web Signature Specification.
- Check the value of
iss(issuer) matches the Issuer Identifier specified in GOV.UK One Login’s discovery endpoint. - Check the
aud(audience) claim is the same client ID you received when you registered your service to use GOV.UK One Login. - Check the
iat(issued at) claim is in the past. - Check the
exp(expiry) claim is in the future. - Check the logout token contains a
sub(subject identifier) claim, otherwise known as the unique ID of a user. - Check the logout token contains an
eventsclaim, which should be a JSON object with a single key:http://schemas.openid.net/event/backchannel-logout– the value for the key should be an empty object. - Check your service has not received another logout token with the same
jticlaim in the last 3 minutes.
If all the validation steps pass, you should close all the sessions for the user whose subject ID matches the sub claim in the payload.
Respond to the back-channel logout request
You must respond to the back-channel logout HTTP request with an HTTP 200 OK response code. This will indicate whether you have received the logout request.