Skip to main content

Choose which user attributes your service can request

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

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 a level of identity confidence.

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 identity proving You can request user attributes using a combination of scopes and claims, 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 request to the /authorize endpoint 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 requests to the /authorize endpoint 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

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.
https://vocab.account.gov.uk/v1/returnCode This claim gives information about any issues with the evidence your user provided to prove their identity, for example, if GOV.UK One Login was not able to prove your user’s identity. This will display as a letter code, for example [{"code": "C"}], in the response.

For security reasons, you’ll have to contact GOV.UK One Login on govuk-one-login@digital.cabinet-office.gov.uk for more detailed information on what issue each return code represents.

If you do not include this claim in your request, GOV.UK One Login returns an access_denied error instead.

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

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 create a configuration for each service you’re integrating.

This page was last reviewed on 9 July 2024.