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,
  "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.

You’ll need a public key to validate this JWT. You can download a Decentralized Identifiers (DID) document containing the current JSON Web Key (JWK) public key – there’s further guidance on validating the core identity claim JWT using a public key.

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 the core identity claim JWT using a public key

To validate the core identity claim JWT, you must use a public key. GOV.UK One Login publishes the public keys in a Decentralized Identifier (DID) document.

Warning GOV.UK One Login regularly rotates its public keys. You must read the guidance on understanding GOV.UK One Login’s key rotation to make sure your application continues to work as expected.

This is an example of a web DID document published by GOV.UK One Login:

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/security/jwk/v1"
  ],
  "id": "did:web:identity.account.gov.uk",
  "assertionMethod": [
    {
      "id": "did:web:identity.account.gov.uk#b7863b6926193d93b48808cbabcbc8a414d0080f81c8779c0a54491551a35816",
      "type": "JsonWebKey",
      "controller": "did:web:identity.account.gov.uk",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "QrP65yghuglwPkEl11oMaabr4WqAMjuvztBYb7T4Ipo",
        "y": "CSQNybYbCZLl-Xr1OA3pcxjC6qZrG7JPqwXgo-9fHLM"
      }
    }
  ]
}

Use the kid (key ID) to see which public key signed the JWT

When validating a JWT, the JWT header will include the kid (key ID). This will be either did:web:identity.integration.account.gov.uk#{UNIQUE_KEY_IDENTIFIER} for the integration environment, or did:web:identity.account.gov.uk#{UNIQUE_KEY_IDENTIFIER} for the production environment.

GOV.UK One Login uses a simplified version of the DID resolution algorithm from the did:web Method Specification. Third-party libraries may have features which ‘resolves’ the DID – this means turning the kid into the URL for the DID document and then downloading the DID. However, you must not use a third-party library’s DID resolution. This could make your application vulnerable to trusting an invalid identity.

You should only trust the DID documents located at:

• integration – https://identity.integration.account.gov.uk/.well-known/did.json
• production – https://identity.account.gov.uk/.well-known/did.json
  

GOV.UK One Login will always publish the DID documents on the URLs above and will never change the publication URLs without notifying you.

Follow the steps below to use the kid to determine which public key from the DID document was used to sign the JWT. This is important because GOV.UK One Login may have rotated its public keys and using the incorrect key will break your integration.

1. Split the kid from the JWT header into two parts: the controller ID (before the #) and the unique key ID (after the #). For example, in the kid did:web:identity.integration.account.gov.uk#c9f8da1c87525bb41653583c2d05274e85805ab7d0abc58376c7128129daa936, the controller ID is did:web:identity.integration.account.gov.uk and the unique key ID is c9f8da1c87525bb41653583c2d05274e85805ab7d0abc58376c7128129daa936.
2. Download the DID document from the DID endpoint you need:
   • Integration: https://identity.integration.account.gov.uk/.well-known/did.json
   • Production: https://identity.account.gov.uk/.well-known/did.json.
3. Make sure the controller ID matches the id in the DID document.
4. Find the object in assertionMethods which has an id field matching the kid from the JWT header. If there are multiple keys in the DID document, GOV.UK One Login is in the process of rotating its keys. If there’s a key without a matching id, do not trust the identity and contact GOV.UK One Login to report an incident.
5. Use the publicKeyJwk object of the key you want to use to verify the signature.

Cache the DID document

You should cache the returned DID document and re-use it instead of downloading the DID document for every signature you need to verify. The DID document will not change often and caching it reduces latency for your service.

The Cache-Control HTTP header field in the DID endpoint contains a suggested caching period. This caching period is how long GOV.UK One Login expects the DID document to remain valid.

For example, a header with the value Cache-Control: max-age=3600, private… would mean you cache the DID document for the max-age of 1 hour (3600 seconds = 1 hour). private stops any other caches or proxies from caching the DID document.

Occasionally, you may not be able to refresh the cache from GOV.UK One Login’s URL, for example if there’s a temporary outage. If this happens, you should continue to trust the cached version until you’re able to refresh the cache.

For more details on the Cache-Control header, see RFC 9111: HTTP Caching.

Understand the core identity signing key rotations

GOV.UK One Login will regularly rotate its keys and may need to rotate keys at short notice. For example, we may rotate a key if it is compromised. New public keys will appear in the assertionMethod array of the DID document before any rotation.

Use the Cache-Control headers and guidance on caching the DID document to regularly poll the DID endpoint to detect new versions and make sure you’re using the latest key.

Once GOV.UK One Login has removed the old public key from the DID document, it will no longer be valid. You should no longer trust verifiable credentials signed with that key.

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 (Vector of Trust) claim in the ID token and make sure the level of protection matches or exceeds the level a user needs to access your service. The vot claim will only contain the credential trust level, not the level of confidence, even if you make an identity request. Additionally, if you ask for medium confidence (P2) you must also request a protection level of Cl.Cm. This means logging in with two-factor authenticaion. If you do not do this, you’ll receive the error: 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, which will each be a letter.
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 issue each returnCode value stands for.
   

Currently, there are 11 returnCode values which GOV.UK One Login could return if there’s an issue with the evidence your user provided to prove their identity. You may receive a return code even if a user’s identity verification is successful, for example, if a user is a politically exposed person. 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,
  "https://vocab.account.gov.uk/v1/returnCode": [
    {
      "code": "B"
    },
    {
      "code": "C"
    }
  ]
}

Continue to managing your users’ sessions.

This page was last reviewed on 9 July 2024.