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
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
- You must validate the JWT signature according to
the JSON Web Signature Specification. Check the JWT
alg
header isES256
and then use the value of the JWTalg
header parameter to validate the JWT. - Check the
iss
claim ishttps://identity.integration.account.gov.uk/
. - Check the
aud
claim matches your client ID you received when you registered your service to use GOV.UK One Login. - Check the
sub
claim matches thesub
claim you received in theid_token
from your token request. - 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:
- You’ll receive an authorisation code in the
redirect_uri
instead of anaccess_denied
error. - Use this authorisation code to get an ID token and an access token.
- 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 morereturnCode
values, for example[{"code": "B"},{"code": "C"}]
. - 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.