Skip to main content

Prove your user’s identity

You must have authenticated your users before you can prove their identity.

If you requested identity proving, when you retrieve user information with /userinfo, you’ll receive a response containing additional claims (user attributes). You may receive different claims, depending on how your user proved their identity.

Your service’s needs will determine how you process the other claims that GOV.UK One Login provides about your user. You’ll probably need to match against information held by your service or organisations you work with.

Most claims are represented by JSON objects. The core identity claim is a JSON web token (JWT) protected by an electronic signature for additional security.

You’ll receive a response from /userinfo that will look similar to this example:

HTTP/1.1 200 OK
Content-Type: application/json

  "sub": "urn:fdc:gov.uk:2022:56P4CMsGh_02YOlWpd8PAOI-2sVlB2nsNU7mcLZYhYw=",
  "email": "test@example.com",
  "email_verified": true,
  "phone": "01406946277",
  "phone_verified": true,
  "updated_at": 1311280970,
  "https://vocab.account.gov.uk/v1/coreIdentityJWT": <JWT>,
  "https://vocab.account.gov.uk/v1/address": [
    {
      "uprn": "10022812929",
      "subBuildingName": "FLAT 5",
      "buildingName": "WEST LEA",
      "buildingNumber": "16",
      "dependentStreetName": "KINGS PARK",
      "streetName": "HIGH STREET",
      "doubleDependentAddressLocality": "EREWASH",
      "dependentAddressLocality": "LONG EATON",
      "addressLocality": "GREAT MISSENDEN",
      "postalCode": "HP16 0AL",
      "addressCountry": "GB",
      "validFrom": "2022-01-01"
    },
    {
      "uprn": "10002345923",
      "buildingName": "SAWLEY MARINA",
      "streetName": "INGWORTH ROAD",
      "dependentAddressLocality": "LONG EATON",
      "addressLocality": "NOTTINGHAM",
      "postalCode": "BH12 1JY",
      "addressCountry": "GB",
      "validUntil": "2022-01-01"
    }
  ],
  "https://vocab.account.gov.uk/v1/drivingPermit": [
    {
      "expiryDate": "2023-01-18",
      "issueNumber": "5",
      "issuedBy": "DVLA",
      "personalNumber": "DOE99802085J99FG"
    }
  ],
  "https://vocab.account.gov.uk/v1/passport": [
    {
      "documentNumber": "1223456",
      "icaoIssuerCode": "GBR",
      "expiryDate": "2032-02-02"
    }
  ],
  "https://vocab.account.gov.uk/v1/socialSecurityRecord": [
    {
      "personalNumber": "QQ123456C"
    }
  ]
}

Understand your user’s core identity claim

The https://vocab.account.gov.uk/v1/coreIdentityJWT property in the /userinfo response is the core identity claim, which is a JWT representing core identity attributes.

The following are core identity attributes:

  • your user’s name
  • your user’s date of birth
  • the level of identity confidence GOV.UK One Login has reached
Warning If the https://vocab.account.gov.uk/v1/coreIdentityJWT property is not present, then GOV.UK One Login was not able to prove your user’s identity.

Our support team will give you the public key you must use to validate this JWT. We recommend you use a certified JWT/JWS implementation.

The JWT contains the following claims:

{
  "sub": "urn:fdc:gov.uk:2022:56P4CMsGh_02YOlWpd8PAOI-2sVlB2nsNU7mcLZYhYw=",
  "iss": "https://identity.integration.account.gov.uk/",
  "aud": "YOUR_CLIENT_ID",
  "nbf": 1541493724,
  "iat": 1541493724,
  "exp": 1573029723,
  "vot": "P2",
  "vtm": "https://oidc.integration.account.gov.uk/trustmark",
  "vc": {
    "type": [
      "VerifiableCredential",
      "VerifiableIdentityCredential"
    ],
    "credentialSubject": {
      "name": [
        {
          "validFrom": "2020-03-01",
          "nameParts": [
            {
              "value": "Alice",
              "type": "GivenName"
            },
            {
              "value": "Jane",
              "type": "GivenName"
            },
            {
              "value": "Laura",
              "type": "GivenName"
            },
            {
              "value": "Doe",
              "type": "FamilyName"
            }
          ]
        },
        {
          "validUntil": "2020-03-01",
          "nameParts": [
            {
              "value": "Alice",
              "type": "GivenName"
            },
            {
              "value": "Jane",
              "type": "GivenName"
            },
            {
              "value": "Laura",
              "type": "GivenName"
            },
            {
              "value": "O’Donnell",
              "type": "FamilyName"
            }
          ]
        }
      ],
      "birthDate": [
        {
          "value": "1970-01-01"
        }
      ]
    }
  }
}

The vc claim in the JWT is a verifiable credential (VC). Claims about your user are contained in the credentialSubject JSON object.

Validate your user’s identity credential

  1. You must validate the JWT signature according to the JSON Web Signature Specification. Check the JWT alg header is ES256 and then use the value of the JWT alg header parameter to validate the JWT.
  2. Check the iss claim is https://identity.integration.account.gov.uk/.
  3. Check the aud claim matches your client ID you received when you registered your service to use GOV.UK One Login.
  4. Check the sub claim matches the sub claim you received in the id_token from your token request.
  5. Check the current time is before the time in the exp claim.

Check your user’s level of authentication protection matches the requested level

You must look for the vot claim in the ID Token and make sure the level of protection matches or exceeds the level a user needs to access your service. If you make an identity request, this vot will only contain the credential trust level, not the level of confidence. Additionally, if you ask for medium confidence (‘P2’) you must also request a protection level of Cl.Cm. This means logging in with second factor authenticaion. If you do not do this, you will receive an error back invalid_request - Request vtr not valid.

Process your user’s identity credential

The identity credential contains the following claims as properties of credentialSubject.

Property Description
name A list showing the names proven by GOV.UK One Login. This list reflects name changes by using the validFrom and validUntil metadata properties. If validUntil is null or not present, that name is your user’s current name. If validFrom is null or not present, your user may have used that name from birth.

Each name is presented as an array in the nameParts property. Each part of the name is either a GivenName or a FamilyName, identified in its type property. The value property could be any text string. GOV.UK One Login cannot specify a maximum length or restrictions on what characters may appear.

GivenName or FamilyName can appear in any order within the list. The order of names may depend on either your user’s preferences or the order they appear on documents used to prove your user’s identity.
birthDate A list of ISO 8601 date strings. There may be multiple dates of birth, for example, if there’s evidence an incorrect date of birth was previously recorded for your user. The date of birth GOV.UK One Login has highest confidence in will be the first item in the list.

Understand your user’s address claim

The https://vocab.account.gov.uk/v1/address claim contains all addresses your user has declared, including previous addresses.

Each JSON object in the list may contain any of the following properties:

Property Definition
validFrom ISO 8601 date strings representing the date your user moved into the address.
If the month is unknown for validFrom, GOV.UK One Login will show that as 01. GOV.UK One Login will also show an unknown day of the month as 01.
validUntil ISO 8601 date strings representing the date your user moved from the address. This property is not included for your user’s current address.
If the month is unknown for validUntil, GOV.UK One Login will show that as 01. GOV.UK One Login will also show an unknown day of month as 01.
uprn GOV.UK One Login will provide a Unique Property Reference Number (UPRN) for UK addresses, unless your user has manually corrected their address.
organisationName Maps to ORGANISATION_NAME in the Postcode Address File and Ordnance Survey Places API.
departmentName Maps to DEPARTMENT_NAME in the Postcode Address File and Ordnance Survey Places API.
subBuildingName Maps to SUB_BUILDING_NAME in the Postcode Address File and Ordnance Survey Places API.

subBuildingName may accompany either buildingName or buildingNumber.
buildingNumber Maps to BUILDING_NUMBER in the Postcode Address File and Ordnance Survey Places API.
buildingName Maps to BUILDING_NAME in the Postcode Address File and Ordnance Survey Places API.
dependentStreetName Maps to DEPENDENT_THOROUGHFARE_NAME in the Postcode Address File and Ordnance Survey Places API.
streetName Maps to THOROUGHFARE_NAME in the Postcode Address File and Ordnance Survey Places API.
doubleDependentAddressLocality Maps to DOUBLE_DEPENDENT_LOCALITY in the Postcode Address File and Ordnance Survey Places API.
dependentAddressLocality Maps to DEPENDENT_LOCALITY in the Postcode Address File and Ordnance Survey Places API.
addressLocality Maps to POST_TOWN in the Postcode Address File and Ordnance Survey Places API.
postalCode Maps to POST_CODE in the Postcode Address File and Ordnance Survey Places API.
addressCountry Two-letter ISO 3166-1 alpha-2 country code.

Do not assume address properties always map to the same line of an address. For example, addressLocality may map to a different line of an address, depending on whether other properties are present (in this case, dependentAddressLocality and doubleDependentAddressLocality).

Understand your user’s passport claim

The https://vocab.account.gov.uk/v1/passport claim contains the details of your user’s passport, if they submitted one when proving their identity.

Property Definition
documentNumber The passport number.
icaoIssuerCode An identifier for the state or organisation that issued the passport. This is defined by the International Civil Aviation Organization (ICAO) standard 9303 Machine Readable Travel Documents. The identifier is up to 3 characters.
expiryDate The expiration date as an ISO 8601 date string.

Understand your user’s driving licence claim

The https://vocab.account.gov.uk/v1/drivingPermit claim contains the details of your user’s driving licence, if they submitted one when proving their identity.

Property Definition
expiryDate The expiry date of the driving licence as an ISO 8601 date string.
issueNumber The last 2 characters of the driving licence number – these show how many times the user has received a new driving licence. You’ll only receive this property for licences issued by the Driver and Vehicle Licensing Agency (DVLA).
issuedBy The organisation that issued the driving licence.
personalNumber The driver number of the driving licence. This is a string unique to the user.

Understand your user’s return code claim

The https://vocab.account.gov.uk/v1/returnCode 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.

To use this claim, you must let us know when registering your service with GOV.UK One Login.

When you use this claim and there’s an issue with the evidence your user provided to prove their identity:

  1. You’ll receive an authorisation code in the redirect_uri instead of an access_denied error.
  2. Use this authorisation code to get an ID token and an access token.
  3. When you make a request to the /userinfo endpoint using the access token, the response may contain only authentication data, and an array of one or more returnCode values, for example [{"code": "B"},{"code": "C"}].
  4. For security reasons, you’ll need to contact GOV.UK One Login on govuk-one-login@digital.cabinet-office.gov.uk for more detailed information on what each return code means.

You may receive a return code even if a user’s identity verification is successful. Contact GOV.UK One Login on govuk-one-login@digital.cabinet-office.gov.uk for more detailed information on what each return code means.

Property Definition
code An array of single letter codes for returnCode values.

You can use these codes to identify the reason(s) for any issues that occurred during the identity proving journey. For security reasons, you’ll need to contact GOV.UK One Login on govuk-one-login@digital.cabinet-office.gov.uk for more detailed information on what each return code means.

If you want to add this feature to an existing integration, contact GOV.UK One Login on govuk-one-login@digital.cabinet-office.gov.uk to update your client registration. You must also update your code to make sure your integration is able to use the new behaviour.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "sub": "urn:fdc:gov.uk:2022:56P4CMsGh_02YOlWpd8PAOI-2sVlB2nsNU7mcLZYhYw=",
  "email": "test@example.com",
  "email_verified": true,
  "phone_number": "01406946277",
  "phone_number_verified": true,
  "updated_at":1311280970,  
  "https://vocab.account.gov.uk/v1/returnCode": [
    {
      "code": "B"
    },
    {
      "code": "C"
    }
  ]
}

Understand your user’s National Insurance number claim

The https://vocab.account.gov.uk/v1/socialSecurityRecord claim contains the details of your user’s National Insurance Number, if they submitted it while proving their identity.

Property Definition
personalNumber The National Insurance number of the user

Continue to log your users out of GOV.UK One Login.

This page was last reviewed on 15 April 2024.