Integrate with Authorization Code Flow

To get an access token which will allow you to access basic user information, you’ll need to integrate with OAuth’s Authorization Code Flow.

We recommend you use a certified OpenID Connect (OIDC) client library rather than building your own.

Use the discovery endpoint

You can use the discovery endpoint to get information needed to interact with GOV.UK One Login, for example:

issuer name
information about the keys
supported scopes, which will contain the user attributes your service can request

Make an authorisation request

To make an authorisation request, your application should first send your user to the authorisation URL.

The way you make an authorisation request will depend on whether you need:

an authentication request only
an authentication and identity assurance request (if you need identity, you must include authentication too)

You can then use one of the following example messages to make a GET request. You should use a certified OIDC client library. Use the guidance in the following table to replace your example message’s placeholder values.

Make an authorisation request for authentication only

If you only need a level of authentication without identity assurance, use this example message to make a GET request.

The following example specifies a medium level of authentication. There’s further guidance on choosing the level of authentication.

You can replace your example message’s placeholder values.

GET /authorize?response_type=code
&scope=YOUR_SCOPES
&client_id=YOUR_CLIENT_ID
&state=STATE
&redirect_uri=YOUR_REDIRECT_URI
&nonce=aEwkamaos5B
&vtr=["Cl.Cm"]
&ui_locales=en

HTTP/1.1
Host: oidc.integration.account.gov.uk

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

Make an authorisation request for authentication and identity

If you need identity assurance as well as authentication, use this example message to make a GET request.

The following example uses medium authentication (Cl.Cm) and a medium level of identity confidence (P2). There’s further guidance on choosing the level of authentication and choosing the level of identity confidence. You can replace your example message’s placeholder values.

GET /authorize?response_type=code
&scope=YOUR_SCOPES
&client_id=YOUR_CLIENT_ID
&state=STATE
&redirect_uri=YOUR_REDIRECT_URI
&nonce=aEwkamaos5B
&vtr=["Cl.Cm.P2"]
&ui_locales=en
&claims=<claims-request>
HTTP/1.1
Host: oidc.integration.account.gov.uk

Create a URL-encoded JSON object for `<claims-request>`

After you’ve made an authorisation request for authentication and identity, you should then use a certified OIDC client library to create a URL-encoded JSON object for <claims-request>. Your JSON object should look similar to this example:

{
  "userinfo": {
    "https://vocab.account.gov.uk/v1/coreIdentityJWT": null,
    "https://vocab.account.gov.uk/v1/address": null,
    "https://vocab.account.gov.uk/v1/passport": null,
    "https://vocab.account.gov.uk/v1/drivingPermit": null
  }
}

You can only request user attributes to be returned in the /userinfo response. You cannot configure the claims returned in the ID token.

Replace your example message’s placeholder values

Use the guidance in the following table to replace placeholder values in your example message.

Parameter	Required or optional	Description
response_type	Required	You must set this value to be code: response_type=code.
scope	Required	A space-separated list of scopes. You must include openid scope value. You should refer to the guidance on choosing which user attributes your service can request for the scope parameter.
client_id	Required	You’ll have set your client_ID when you registered your service to use GOV.UK One Login.
state	Required	When you receive a response at the redirect URL, there must be a way to verify the response came for a request which you sent. The state value solves this issue by binding the request and response, which reduces impact of Cross Site Request Forgery attacks. This value will be returned to the client in the authentication response.
redirect_uri	Required	You’ll have specified your redirect_uri when you registered your service to use GOV.UK One Login. The redirect URI must exactly match one of the redirect URIs you registered for using Dynamic Client Registration, except that it must be URL-encoded.
nonce	Required	A unique value generated by your application that is used to verify the integrity of the id_token and mitigate replay attacks. This value will be present in the id_token and should include the per-session state, as well as being impossible for attackers to guess. Your application will need to verify the nonce claim value is the same as the nonce parameter sent in the authentication request.
ui_locales	Optional	GOV.UK One Login supports English and Welsh as language choices. If your service is in Welsh, you may want to display GOV.UK One Login in Welsh for a consistent user experience. You can use `ui_locales` to do this. In the `ui_locales` parameter, you can choose either `en` (English) or `cy` (Welsh). Using `ui_locales` is optional. If you do not include it, your service will continue using English by default. GOV.UK One Login does not support any other languages.
vtr	Optional	The `vtr` parameter represents ‘Vectors of Trust’ where you request authentication and, optionally, identity assurance. For example, if you want the medium level of authentication and medium identity confidence, request `vtr=[“Cl.Cm.P2”]`. You selected your Vector of Trust when you chose the level of authentication and the level of identity confidence for your service. You can read more about how to combine the vectors for authentication level and identity confidence in Section 3 of RFC 8485. If you need identity assurance, you must request `Cl.Cm` (the medium level of authentication) or higher (higher levels of authentication will be available soon). If you do not specify the `vtr` parameter, your service will automatically log your users in at the medium level of authentication (`Cl.Cm`). This means you will not receive identity attributes in your response.
claims	Optional	To get the identity attributes your service needs, you should specify these in the `claims` parameter using the `/userinfo` endpoint. The `/userinfo` endpoint returns a JSON object listing the requested claims. You can read more about choosing which user attributes your service can request. You can read more about the structure of the claims request in OpenID Connect section 5.5.

Generate an authorisation code

If your user does not have an existing session they’re signed in to when your service makes the authorisation request, the OIDC sign-in page will open. Your user can enter their details on this page to authenticate themselves.

If your user has an existing session, or after they authenticate, they will be redirected to the redirect_uri your service specified.

The authorisation code generated by your user’s session can be used once and displays in the query string of the URL, for example:

HTTP/1.1 302 Found
Location: https://YOUR_REDIRECT_URI?code=AUTHORIZATION_CODE&state=xyzABC123

If your authorisation request included the state parameter, the URI will also include this parameter.

Error handling for ‘Make an authorisation request’

To understand more about what the error is, you can look in the response. Depending on the type of error you receive, the response may contain an error and an error_description which will provide you with information.

If there’s an error in your request, you’ll be redirected to the URI you specified for redirect_uri in the authorisation URL. You’ll be able to see the error description tagged onto the end of the authorisation URL, for example:

HTTP/1.1 302 Found
Location: https://YOUR_REDIRECT_URI?error=invalid_request
&error_description=Unsupported%20response
&state=1234

Error	More information about your error
unauthorized_client	Your service is not authorised to request an authorisation code. Make sure you have registered your service to use GOV.UK One Login.
invalid_request	The request has one or more of the following issues: missing a required parameter includes an invalid parameter value includes a parameter more than once not in the correct format You can check which parameters GOV.UK One Login supports when you make an authorisation request.
invalid_scope	The scope or scopes you have requested are invalid, unknown, or are not in the correct format. You can read more about scopes in choosing which user attributes your service can request.
unsupported_response_type	Your service is not registered for the requested `response_type`. You must set the `response_type` to be code: `response_type=code`.
server_error	The GOV.UK One Login authentication server has experienced an internal server error.
temporarily_unavailable	If you’re only making an authentication request (as opposed to requesting both authentication and identity), this error code means the GOV.UK One Login authentication server is temporarily unavailable, which might be caused by temporary overloading or planned maintenance. Make your authorisation request again in a few minutes. If you’re making an identity request and you get this error, it means the identity proofing and verification does not currently have capacity for this request.
access_denied	GOV.UK One Login returns this error in 3 potential scenarios. The first scenario is that the identity evidence your user provided has a lower score than the identity confidence specified in your request. As a result, GOV.UK One Login could not return the medium level of identity confidence (`P2`) and instead returned a lower level of identity confidence. The second scenario is that your user selected Cancel during the identity verification process. The third scenario is that the session in the user’s browser is unavailable. This can happen when your user’s cookies have been lost or your user changed browsers during the identity verification process. In this scenario, you should ask your user to log in again or restart the identity verification process.

Make a token request

You need to exchange your authorisation code for tokens. You’ll use these tokens to make a call to the /userinfo endpoint.

To exchange your authorisation code for tokens, you’ll need to make a POST request to the /token endpoint using the client authentication method private_key_jwt.

Before you can make a POST request, you need to:

Create a JWT assertion.
Include the JWT assertion in your POST request.

GOV.UK One Login will then authenticate your request by verifying the signature and payload of the JWT assertion. This authentication will generate a token response, which will include:

an access token
an ID token
a refresh token - you’ll use this if you want to access the /userinfo endpoint for longer than 3 minutes

Create a JWT assertion

To create a JWT assertion, you need to:

Use the key pair you generated earlier in the process.
Create a JWT.
Sign your JWT with the key you created - how you sign your JWT will vary depending on the language you’re using.

Create a JWT

To create a JWT assertion, you need to create a JWT which contains certain required claims. There’s some optional claims you can choose to include or not include.

Claim	Required or recommended	Description
aud	Required	`aud` stands for ‘audience’. This identifies GOV.UK One Login’s authorisation server as an intended audience. This value should be the URL: https://oidc.integration.account.gov.uk/token.
iss	Required	`iss` stands for ‘issuer’. This claim should contain your `client_id` you created when you registered your service to use GOV.UK One Login.
sub	Required	`sub` stands for ‘subject’. This claim should contain your `client_id` you created when you registered your service to use GOV.UK One Login.
exp	Required	`exp` stands for ‘expiration time’. This is the expiration time for this token, which must be an integer timestamp representing the number of seconds since the Unix Epoch This is the time after which you must not accept the JWT. We recommend an expiration after 5 minutes. The current date and time must be before the expiration date and time listed in the `exp` claim.
jti	Required	`jti` stands for ‘JWT ID’. In this claim, you should include a unique identifier for the token. This unique identifier will prevent the token being reused as your application must only use these tokens once.
iat	Recommended	`iat` stands for ‘issued at’. This identifies the time at which your application created the JWT. You can use this claim to understand the age of the JWT. This must appear as an integer timestamp representing the number of seconds since the Unix Epoch.

Your JWT body will look similar to this example:

{
  "aud":"https://oidc.integration.account.gov.uk/token",
  "iss":"38174623762",
  "sub":"38174623762",
  "exp":1536165540,
  "jti":"RANDOM_VALUE_JTI",
  "iat":1536132708
}

Once you have created your JWT and signed your JWT with the key pair, you have created your JWT assertion.

Make a `POST` request to the `/token` endpoint

Now you have generated your JWT assertion, you’re ready to make a POST request to the /token endpoint, for example:

POST /token HTTP/1.1
Host: oidc.integration.account.gov.uk
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient.example.org%2F
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIiLCJpc3MiOiIiLCJhdWQi
OiIiLCJqdGkiOiIifQ.r1Ylfhhy6VNSlhlhW1N89F3WfIGuko2rvSRWO4yK1BI

Parameter	Required or recommended	Description
grant_type	Required	If you’re requesting a refresh token, you must set this parameter to `refresh_token`. Otherwise, you need to set the parameter to `authorization_code`.
redirect_uri	Required	You’ll have specified your `redirect_uri` when you made the initial authorisation request.
client_assertion	Required	You’ll include the JWT assertion you created in the payload when you make the `POST` request to the `/token` endpoint.
client_assertion_type	Required	When you’re using `private_key_jwt`, you must set the value to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
code	Required	The code you received when you generated an authorisation code.

Receive response for ‘Make a token request’

If your token request is successful, the /token endpoint will return a response similar to this example:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "SlAV32hkKG",
  "refresh_token": "i6mapTIAVSp2oJkgUnCACKKfZxt_H5MBLiqcybBBd04",
  "token_type": "Bearer",
  "expires_in": 180,
  "id_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc
    yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg"
}

You can use the following table to understand the response for ‘Make a token request’.

Parameter	Description
access_token	The access token value is an opaque access token which you can use with the `/userinfo` endpoint to return a user’s profile.
refresh_token	You can use a refresh token if you need to request a new access token.
token_type	The token type value. GOV.UK One Login only supports the bearer token.
expires_in	The length of time the token is valid for. This is displayed in seconds.
scope	You can read more about scopes in choosing which user attributes your service can request.
id_token	A signed JWT that contains basic attributes about the user. By default, GOV.UK One Login signs this JWT using the `ES256` algorithm. If your service cannot support the `ES256` algorithm (for example, some third-party tooling does not support `ES256`), GOV.UK One Login can sign the JWT using the `RS256` algorithm. You’ll have specified whether your service can support `ES256` when you registered your service to use GOV.UK One Login. The public key used to verify this JWT is available from the `jwks_uri` parameter found in the discovery endpoint.

Understand your ID token

The id_token parameter in the response for ‘Make a token request’ contains the following claims:

{
  "sub": "urn:fdc:gov.uk:2022:56P4CMsGh_02YOlWpd8PAOI-2sVlB2nsNU7mcLZYhYw=",
  "iss": "https://oidc.integration.account.gov.uk",
  "nonce": "aad0aa969c156b2dfa685f885fac7083",
  "aud": "YOUR_CLIENT_ID",
  "exp": 1489694196,
  "iat": 1489694198,
  "sid": "LeiKvyPXZorTmSgOTsYhPehsGNw="
}

You can use the following table to understand the ID token’s claims.

Claim	Description
sub	The subject identifier or the unique ID of a user.
iss	The GOV.UK One Login OpenID Provider’s Issue identifier as specified in the discovery endpoint.
nonce	The `nonce` value your application provided when you made the authorisation request.
aud	The audience, which will be the `client_id` you set when you registered your service to use GOV.UK One Login.
exp	`exp` means ‘expiration time’. This is the expiration time for this token, which will be an integer timestamp representing the number of seconds since the Unix Epoch.
iat	`iat` stands for ‘issued at’. This identifies the time at which GOV.UK One Login created the JWT. You can use this claim to understand the age of the JWT.This will appear as an integer timestamp representing the number of seconds since the Unix Epoch.
sid	`sid` stands for ‘session identifier’. This uniquely identifies the user’s journey within GOV.UK One Login.

Now you’ve understood what’s in your ID token, you’ll need to validate it.

Validate your ID token

If you’re using a library, check whether your library has support for validating ID tokens.
The value of iss must exactly match the Issuer Identifier as specified in GOV.UK One Login’s discovery endpoint.
The aud claim must contain your client ID you received when you registered your service to use GOV.UK One Login.
You must validate the signature according to the JSON Web Signature Specification. You must first validate that the JWT alg header matches what was returned from the jwks_uri. Then you can use the value of the JWT alg header parameter to validate the ID token. Your application must use the keys provided by the discovery endpoint.
Check the current time is before the time in the exp claim.
If you set a nonce value in the authorisation request, check the nonce value in the authorisation request matches the nonce value in the ID token.
Check the ID token is between the auth_time claim value (when the token was issued) and the exp claim value. If your ID token is outside this time window, you’ll need to request re-authentication from your user.

Error handling for ‘Make a token request’

If the token request is invalid or unauthorised, you’ll receive an error response with the Content-Type of application/json, for example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "invalid_request"
  "error_description": "invalid scope"
}

Error	More information about your error
invalid_request	The request is missing a parameter so the server cannot proceed with the request. This error may also be returned if the request includes an unsupported parameter or repeats a parameter. Review your parameters and check they are supported and not repeated.
invalid_client	Client authentication failed, which could be caused by the request containing an invalid client ID. To resolve, check your client ID matches the client ID you had when you registered your service to use GOV.UK One Login.
invalid_grant	The authorisation code is invalid or expired. This is also the error which would return if the redirect URL given in the authorisation request does not match the URL provided in this access token request.
unauthorized_client	The application is successfully authenticated, but it’s not registered to use the requested grant type.
unsupported_grant_type	The grant type is not supported by the server.

Use your refresh token to request a new access token

A GOV.UK One Login access token is valid for 3 minutes. After 3 minutes, you cannot use an access token to make a call to /userinfo.

If you want to access the /userinfo endpoint for longer than 3 minutes, you should use a refresh token to refresh your access token.

Using a refresh token is optional. To use a refresh token, you’ll need to include the offline_access scope. You can read more about scopes in choosing which user attributes your service can request.

A refresh token lasts longer than an access token. You can find the refresh token’s lifespan in the refresh token’s claims.

To generate your refresh token, you need to make a request to the /token endpoint. In your request, you need to:

Fill in the parameters the same way as when you made a POST request to the /token endpoint for your access token.
Leave grant_type as refresh_token.

POST /token HTTP/1.1
Host: oidc.integration.account.gov.uk
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=i6mapTIAVSp2oJkgUnCACKKfZxt_H5MBLiqcybBBd04

Receive response for ‘Make a refresh token request’

If your token request is successful, the /token endpoint will return a response similar to this example:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "SlAUH9V32hkKG",
  "refresh_token": "nJ8tfWD",
  "token_type": "Bearer",
  "expires_in": 180
}

Error handling for ‘Make a refresh token request’

If the token request is invalid or unauthorised, you’ll receive an error response with the Content-Type of application/json, for example:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
  "error": "invalid_request"
  "error_description": "invalid scope"
}

Error	More information about your error
invalid_request	The request is missing a parameter so the server cannot proceed with the request. This error may also be returned if the request includes an unsupported parameter or repeats a parameter. Review your parameters and check they are supported and not repeated.
invalid_client	Client authentication failed, which could be caused by the request containing an invalid client ID. To resolve, check your client ID matches the client ID you had when you registered your service to use GOV.UK One Login.
invalid_grant	The authorisation code is invalid or expired. This is also the error which would return if the redirect URL given in the authorisation request does not match the URL provided in this access token request.
unauthorized_client	The application is successfully authenticated, but it’s not registered to use the requested grant type.
unsupported_grant_type	The grant type is not supported by the server.

Retrieve user information

You can retrieve information about your users by making a request to the /userinfo endpoint.

Make the request to the /userinfo endpoint using the access token you received when making a token request. Using the authorisation header field, send the access token as a bearer token. You’ll receive a JSON object which contains a collection of name and value pairs.

An example request to the /userinfo endpoint would look similar to this example:

GET /userinfo HTTP/1.1
Host: oidc.integration.account.gov.uk
Authorization: Bearer <access_token>

Receive response for ‘Retrieve user information’

The response you’ll get after making a request to the /userinfo endpoint will be a JSON object containing user attributes.

If you included all the scopes when you were choosing which user attributes your service can request and made a request to the /userinfo endpoint, the response would look similar to this:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "sub": "b2d2d115-1d7e-4579-b9d6-f8e84f4f56ca",
  "email": "test@example.com",
  "email_verified": true,
  "phone_number": "01406946277",
  "phone_number_verified": true,
  "updated_at":1311280970
}

If you included a level of identity confidence when you made a request to the /userinfo endpoint, you’ll also see identity attributes in the response. You can read more about how to process your user’s identity information.

Error handling for ‘Retrieve user information’

When a request fails, the /userinfo endpoint will respond with:

an HTTP status code (usually 401 or 403)
an error code (usually error parameter and an error description) included in the response

An error response for the /userinfo endpoint would look similar to this example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token",
error_description="The Access Token expired"

Error	More information about your error
invalid_token	GOV.UK One Login denied your request as you have an invalid or missing bearer access token. To proceed, you must use the authorisation header field to send the token as a bearer token.

This page was last reviewed on 11 November 2022.

Cookies on GOV.UK Sign In