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:
|
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
}
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
- 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 thejwks_uri
. Then you can use the value of the JWTalg
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 thenonce
value in the authorisation request matches thenonce
value in the ID token. - Check the ID token is between the
auth_time
claim value (when the token was issued) and theexp
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:
- 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
asrefresh_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. |