Skip to main content

Process your user’s identity information

If you requested identity assurance, 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"
      }
    ]
}

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/",
  "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 sub claim matches the sub claim you received in the id_token from your token request.
  4. Check the current time is before the time in the exp claim.

Check your user’s identity credential matches the level of confidence needed

You must check the vot claim in the JWT matches or exceeds the level of confidence you need to let your user access your service. You may receive a lower level of confidence than you requested. For example, if you asked for medium confidence (P2), you may receive an identity credential containing low confidence (P1 in the vot claim).

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.
This page was last reviewed on 20 January 2023.