Log your users out of GOV.UK One Login

You must set up the functionality to log your 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 GET request to GOV.UK One Login’s /logout endpoint to end your user’s session.

HTTP/1.1 GET
Location: https://oidc.integration.account.gov.uk/logout?
id_token_hint=eyJraWQiOiIxZTlnZGs3I...
&post_logout_redirect_uri=http://example-service.com/my-logout-url
&state=sadk8d4--lda%d

Warning This code example uses formatting that makes it easier to read. If you copy the example, you must make sure the request is:
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`.

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 their session.

GOV.UK One Login can notify you using a POST request when a user who has logged into your service using GOV.UK One Login has logged out. These notifications are optional, but we recommend supporting them to maintain a consistent user experience.

The logout notifications follow the OIDC back-channel logout specification.

There’s an example implementation of handling a back-channel logout notification.

Opt in to logout notifications

You opt in to receive logout notifications by providing a back_channel_logout_uri when you register your service to use GOV.UK One Login.

When you receive a logout notification for an end user, you should close all the sessions you hold for that user in your service.

Receive the back-channel logout request

You must make sure your back_channel_logout_uri can accept POST requests from GOV.UK One Login.

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 back-channel logout request:

  {
   "iss": "https://server.example.com",
   "sub": "248289761001",
   "aud": "s6BhdRkqt3",
   "iat": 1471566154,
   "jti": "bWJq",
   "sid": "08a5019c-17e1-4977-8f42-65a12843ea02",
   "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. You should handle the first of these logout notifications and ignore any following requests.

Validate the signature of a back-channel logout request

Once you’ve received a POST request to your back_channel_logout_uri, you need to validate the JWT signature according to the JSON Web Signature Specification.

You must validate that the JWT alg header matches what the jwks_uri returned.
Use the value of the JWT alg header parameter to validate the JWT. Your application must use the public keys provided by the discovery endpoint.

After you do these steps, you’ve validated the signature of the back-channel logout request. Next, you need to validate the payload’s content.

Validate the payload’s content for a back-channel logout request

Check the value of iss exactly matches the Issuer Identifier specified in GOV.UK One Login’s discovery endpoint.
Check the aud claim is the same client ID you received when you registered your service to use GOV.UK One Login.
Check the iat (issued at) value is in the past.
Check the logout token contains a sub claim - this is the subject identifier, otherwise known as the unique ID of a user.
Check the logout token contains an events claim, which should be a JSON object with a single key: http://schemas.openid.net/event/backchannel-logout, and the value for that key should be an empty object.
Verify the logout token does not contain a nonce claim.
Check your service has not recently received another logout token with the same jti value.

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 response code, which will indicate whether you were able to log the user out.

HTTP status code	Description
`HTTP 200 OK`	You successfully closed all the user’s sessions.
`HTTP 400 Bad Request`	You were unable to validate the payload. Check you have validated it correctly.
`HTTP 501 Not Implemented`	You have not been able to log the user out of your service. Diagnose any issues with your service but do not replay the logout if the payload has expired.
`HTTP 504 Gateway Timeout`	You have successfully closed all the user’s sessions in the receiving service but have not been able to close one or more related sessions in related services.

Continue to test your integration with GOV.UK One Login.

This page was last reviewed on 30 May 2022.

Cookies on GOV.UK Sign In