Skip to main content

How GOV.UK One Login works

GOV.UK One Login is an OpenID Connect (OIDC)-compliant service that helps you authenticate users logging into your service.

GOV.UK One Login follows the Service Manual for designing for different browsers and devices.

GOV.UK One Login uses 2 different environments:

  • an integration environment, which contains sample user data (for example, date of birth, address) which you can use to test your service’s integration with GOV.UK One Login
  • a production environment, which is the live environment for real users to access and use your service’s integration with GOV.UK One Login

GOV.UK One Login OIDC Authorization Code Flow

The diagram shows how your service interacts with GOV.UK One Login to authenticate a user and retrieve their information following the OIDC protocol.

It shows how keys are used to sign and verify requests and tokens to make sure there is a secure communication between your service and GOV.UK One Login.

Retrieve OIDC metadata

  1. Your service sends a GET request to the GOV.UK One Login /.well-known/openid-configuration endpoint to fetch the discovery document. This document contains the metadata describing GOV.UK One Login’s behaviour as an OIDC provider.
  2. GOV.UK One Login returns a discovery document describing GOV.UK One Login’s behaviour as an OIDC provider.

You should cache the discovery document.

Authorise

  1. Your service creates a JWT containing the authorize request parameters and signs a request with its private key.
  2. Your service initiates an authentication redirect to GOV.UK One Login.
  3. The user agent sends a GET request to the /authorize endpoint.
  4. GOV.UK One Login fetches the public keys from your JWKS endpoint registered for your service. It will only call your JWKS endpoint if its cache does not contain a key that relates to a kid in a received JWT.
  5. Your service returns the public keys as a JWKS document. GOV.UK One Login caches these keys for 24 hours.
  6. GOV.UK One Login validates the authorize request. This includes validating the request JWT signature using the public key from the JWKS that matches the kid specified in the request JWT header.
  7. The user logs in or creates an account and optionally proves their identity through GOV.UK One Login.
  8. GOV.UK One Login sends an HTTP 302 redirect to the user agent specifying your service’s redirect URI and including an authorisation code.
  9. The user agent sends a GET request to your service’s redirect URI including the provided authorisation code.

Exchange the authorisation code for an ID token and an access token

  1. Your service creates a JWT assertion and signs it with its private key.
  2. Your service sends a POST request to the /token endpoint, including the authorisation code and assertion.
  3. GOV.UK One Login sends a GET request to your /.well-known/jwks.json endpoint to fetch your public keys, which verify the signature on the request JWT passed in your authorize request.
  4. Your service returns the public keys as a JWKS document. GOV.UK One Login caches these keys for 24 hours.
  5. GOV.UK One Login validates the token request. This includes validating the assertion JWT signature using the public key from the JWKS that matches the kid specified in the assertion JWT header.
  6. GOV.UK One Login returns an ID token and an access token to your service.
  7. Your service fetches the public keys from the GOV.UK One Login JWKS endpoint. The url for the endpoint is specified in the the jwks_uri object in the discovery document retrieved from the GOV.UK One Login /.well-known/openid-configuration.
  8. GOV.UK One Login returns its public keys as a JSON Web Key Set.
  9. Your service validates the signature of the ID token using the public key.

Retrieve userinfo

  1. Your service sends a GET request to the /userinfo endpoint, including the access token received in response to the POST /token request.
  2. GOV.UK One Login returns the userinfo (including a core identity claim if requested).
  3. Your service sends a GET request to the GOV.UK One Login /.well-known/did.json to fetch its public keys, which verify the signature on the core identity claim JWT issued by GOV.UK One Login.
  4. GOV.UK One Login returns its public keys in a DID document.
  5. Your service validates the signature of the core identity claim with the public key from the DID document with the matching kid.
This page was last reviewed on 8 January 2026.