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 Sign In, 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"]

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 (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"]
&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
  }
}

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 Sign In.
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 Sign In.
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 Sign In supports the login parameter. This will always force your users to re-authenticate even if they have an existing session.
If you use the prompt parameter, 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.
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 information 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 Sign In.
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 Sign In 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 Sign In 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 Sign In 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.

    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 Sign In 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 Sign In’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 Sign In.
    sub Required sub stands for ‘subject’. This claim should contain your client_id you created when you registered your service to use GOV.UK Sign In.
    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=rn%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": 3600,
      "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 Sign In 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. GOV.UK Sign In signs this JWT using the ES256 algorithm.
    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 Sign In 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 Sign In.
    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 Sign In 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 Sign In’s discovery endpoint.
    3. The aud claim must contain your client ID you received when you registered your service to use GOV.UK Sign In.
    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 Sign In.
    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 Sign In 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": 3600
    }
    

    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 Sign In.
    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 Sign In 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 14 October 2021.