Choose which user attributes your service can request

Your service can request certain user attributes. To do this, you need to choose which ‘scopes’ or ‘claims’ your service will use and include these when you make your authorisation request.

OpenID Connect (OIDC) scopes are identifiers your application uses during authentication to authorise access to a user’s attributes, such as an email address. Each scope returns a set of user attributes contained within it. OIDC calls this set of user attributes ‘claims’.

The user attributes and how you request them will depend on whether you are requesting authentication only, or authentication with identity assurance.

Type of request you’re making	What type of user attributes you can request
Authentication only	You can only request user attributes using scopes.
Authentication and P1 identity assurance	You can only request user attributes using scopes.
Authentication and P2 (or higher) identity assurance	You can request user attributes using both claims and scopes (or either claims or scopes, depending on what your service needs).

You’ll need to agree which scopes and claims you want to use when you register your service to use GOV.UK One Login.

Choose which scopes your service can request

openid is the only scope you must include. You can choose to include other scopes for your authorisation request depending on the user attributes your service needs.

You can find details of the scopes in the following table.

Scope	Required or optional	Description
openid	Required	OIDC authorisation requests must contain the openid scope value to indicate that an application intends to use the OIDC protocol. This will return the sub claim, which uniquely identifies your user.
email	Optional	Returns the email claim, which contains: your user’s email address email_verified, which is a boolean indicating whether your user has verified their email address or not
phone	Optional	Returns the phone_number claim, which contains: your user’s phone number phone_number_verified, which is a boolean indicating whether your user has verified their phone number or not
offline_access	Optional	You use an access token to make calls to the /userinfo endpoint. If you want to access the /userinfo endpoint for longer than 3 minutes, you should use a refresh token to refresh your access token. If you want a refresh token, you must request the offline_access scope.

Choose which claims your service can request

You can also request specific claims from GOV.UK One Login, if you need more information than the scopes in the previous section can provide. You must choose a level of identity confidence P2 or above, otherwise you will not receive any claims in the authorisation response.

You can find details of the claims in the following table.

Claim	Description
https://vocab.account.gov.uk/v1/coreIdentityJWT	This claim contains core identity information about your user: their names their date of birth the level of confidence GOV.UK One Login reached in your user’s identity
https://vocab.account.gov.uk/v1/address	This claim contains your user’s postal addresses.
https://vocab.account.gov.uk/v1/passport	This claim contains your user’s passport details if GOV.UK One Login proved their identity using their passport. If GOV.UK One Login did not prove your user’s identity using their passport, the authorisation response will not return this claim.
https://vocab.account.gov.uk/v1/drivingPermit	This claim contains your user’s driving licence details if GOV.UK One Login proved their identity using their driving licence. If GOV.UK One Login did not prove your user’s identity using their driving licence, the authorisation response will not return this claim.

You can see more about the structure of this information when you process your user’s identity information.

You can only ask us for claims that are covered by your Data Protection Impact Assessment. You must clearly explain to your users why you are collecting the data and what you will use it for.

Once you have chosen which attributes your service can request, you can manage your service’s configuration with GOV.UK One Login.

This page was last reviewed on 27 June 2022.