Skip to main content

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

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.
prompt Optional GOV.UK One Login supports the login prompt value. This will always force your users to re-authenticate even if they have an existing session.
If you use the login prompt value, your users will be prompted to authenticate.
If you do not use the prompt parameter, your service will silently authenticate your users if they have an existing session.
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:

    1. Create a JWT assertion.
    2. 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:

    1. Use the key pair you generated earlier in the process.
    2. Create a JWT.
    3. 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
}

    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.

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

    Validate your ID token

    1. If you’re using a library, check whether your library has support for validating ID tokens.
    2. The value of iss must exactly match the Issuer Identifier as specified in GOV.UK One Login’s discovery endpoint.
    3. The aud claim must contain your client ID you received when you registered your service to use GOV.UK One Login.
    4. 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.
    5. Check the current time is before the time in the exp claim.
    6. 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.
    7. 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’

    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 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:

    1. Fill in the parameters the same way as when you made a POST request to the /token endpoint for your access token.
    2. 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’

    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 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": "01406946277",
  "phone_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’

    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.

    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.