JSON Web Key Set (JWKS)
The JWKS endpoint is a required endpoint that exposes the credential issuer’s public cryptographic keys, which can be used by GOV.UK Wallet to verify the pre-authorised code, in JSON Web Key Set (JWKS) format.
This endpoint lets the GOV.UK One Login retrieve the credential issuer’s public keys and then verify the pre-authorised code signature. This process confirms that the pre-authorised code was issued by the expected credential issuer and that it has not been tampered with.
Technical details
Endpoint location
The JWKS must be publicly accessible at the standardised location /.well-known/jwks.json on the credential issuer’s domain.
Response format
The endpoint must return a 200 OK HTTP status code and a valid JSON response that follows the JWKS specification defined in RFC 7517. Each key within the JWKS is represented as a JSON Web Key (JWK) object. The JWKS usually contains only one key, but it can contain two keys during a key rotation overlap period.
The JWK for an elliptic curve key based on the P-256 curve must include the following parameters:
kty: The family of cryptographic algorithms used with the key - must be “EC”.kid: A unique identifier for a specific key within the set - this value will be referenced in the pre-authorised code header to show which key was used for signing and which key must be used for verification. This parameter is important for associating the correct public key with the pre-authorised code being verified.crv: Cryptographic curve used with the key - must be “P-256”.x: The “x” coordinate for the elliptic curve point.y: The “y” coordinate for the elliptic curve point.alg: The cryptographic algorithm used with the key - must be “ES256”.use: The intended use of the key - must be “sig” to indicate a signing key.
JWKS example
Below is an example of a JWKS containing one elliptic curve key based on the P-256 curve:
{
"keys": [
{
"kty": "EC",
"use": "sig",
"crv": "P-256",
"kid": "5dcbee863b5d7cc30c9ba1f7393dacc6c16610782e4b6a191f94a7e8b1e1510f",
"x": "6jCKX_QRrmTeEJi-uiwcYqu8BgMgl70g2pdAst24MPE",
"y": "icPzjbSk6apD_SNvQt8NWOPlPeGG4KYU55GfnARryoY",
"alg": "ES256"
}
]
}