Skip to main content

Log your users out of GOV.UK Sign In

You must set up the functionality to log your users out of a GOV.UK Sign In session.

  1. Log your user out of using your application - the way you do this will depend on how you have built your service.
  2. In the user’s browser, make a GET request to GOV.UK Sign In’s /logout endpoint to end your user’s session.

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

If no GOV.UK Sign In session exists, for example if the session has expired, the endpoint redirects your user to the default logout page for GOV.UK Sign In. Your user can continue their journey from the default logout page.

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 Sign In 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 Sign In 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 Sign In.
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 users out of GOV.UK Sign In’

After you have made your GET request to GOV.UK Sign In’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 Sign In and terminated their session.

Responding to logout notifications from GOV.UK Sign In

GOV.UK Sign In can notify you using a POST request when a user who has logged into your service using GOV.UK Sign In 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 Sign In.

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 Sign In.

GOV.UK Sign In will send a POST request to your back_channel_logout_uri when a user who has logged into your service using GOV.UK Sign In 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.

  1. You must validate that the JWT alg header matches what the jwks_uri returned.
  2. 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

  1. Check the value of iss exactly matches the Issuer Identifier specified in GOV.UK Sign In’s discovery endpoint.
  2. Check the aud claim is the same client ID you received when you registered your service to use GOV.UK Sign In.
  3. Check the iat (issued at) value is in the past.
  4. Check the logout token contains a sub claim - this is the subject identifier, otherwise known as the unique ID of a user.
  5. 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.
  6. Verify the logout token does not contain a nonce claim.
  7. 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.
This page was last reviewed on 30 May 2022.