Set up your public and private keys

GOV.UK One Login uses public key cryptography to authenticate requests received from your services. You need to create a pair of cryptographic keys if your service either:

provides a request JSON Web Token (JWT) in its /authorize requests
sets Private_key_jwt as the Token Authentication method

Your key pair will consist of a private key and its corresponding public key.

You need to share your public key with GOV.UK One Login so it can validate the signature on each JWT your service sends.

Create a key pair

You can create a key pair using OpenSSL.

Install OpenSSL, and create a key pair by running this command in your command line:

openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

openssl rsa -pubout -in private_key.pem -out public_key.pem

The openssl genpkey command generates a private key or key pair using OpenSSL.

Parameter and value	Description
`-algorithm RSA`	Sets RSA as the public key algorithm used to create the key pair.
`-out private_key.pem`	Saves the contents of the private key to a file named private_key.pem.
`-pkeyopt rsa_keygen_bits:2048`	Sets the public key to 2048 bits.

The openssl rsa command processes RSA keys to print the contents of the keys to a file.

Parameter and value	Description
`-pubout`	Creates a public key from a given private key file.
`-in private_key.pem`	Uses the specified private key file to create a corresponding public key.
`-out public_key.pem`	Saves the contents of the public key created to a file named public_key.pem.

You have now created your key pair. They will appear as 2 separate files on your machine:

public_key.pem - this is your public key, which you will need to share with GOV.UK One Login
private_key.pem - this is your private key which you should store securely and not share

Warning Once you’ve created your private key, you should store the key in a secure location, such as a file vault. You should not share your private key. You should also create a new key pair for each environment you use.

You need to share your public keys with GOV.UK One Login to use both the integration and production environment. You can share your public keys using one of the following methods:

a JSON Web Key Set (JWKS) endpoint - strongly recommended
a fixed public key - not recommended for production

A JWKS endpoint is a read-only URL that returns JWKSs in JSON format. It lets you share one or more keys simultaneously without affecting your service availability. You can also rotate your keys without needing to request GOV.UK One Login for a configuration change. You can read the formal description of JWKS in this RFC.

Sharing a fixed public key is a quick way to get started with GOV.UK One Login and to test your integration. However it is not recommended in the production environment.

We recommend using a JWKS endpoint to share your public keys. To make sure your endpoint is compatible and works with GOV.UK One Login, it must:

use the HTTPS scheme
be publicly accessible
respond to a HTTP GET request
return a HTTP 200 (OK) with a JWKS within 5 seconds of a GET request
return one or more RSA signing keys in JWKS format
return a unique Key ID (kid) parameter in each (JWKS) entry

Your JWKS endpoint should give a JSON response similar to the following example:

{
  "keys": [
    {
      "kty": "RSA",
      "e": "AQAB",
      "use": "sig",
      "kid": "f58a6bef-0d22-444b-b4d3-507a54e9892f",
      "n": "pSx43eUV2hZ3AJKYNFHxOsILQ_tUNpfPVELCy3js3FsTp5Mcbpb8mu-arekTCq0Mx5-uqRhJKuT1eGf5DIsb69P__Eyi787Q2o5CdbDwB4iUlEffgx_KuOWUm_4YEuVSjnxfS_hB9h_38zQ6WtD1NnCbcMk4RT2MRvCSiIr9OhjKn9AExH7aaDY7nPm0uVybMkNf5hzBBJWsblBGLmFqnw-qHIEGJaC0M2yZEfXJDbdeZx-IYEYMi3QrR_y4yWzQP2RC8QDU84-uj5mAy5vn06RSdAHNXdiuUX3dIFlerri8gSXo5dPps-gU7igauHnX6mP0HBDtnoNKcM1gpXrnKw"
    }
  ]
}

Warning If you are sharing your public keys using a JWKS endpoint, you must provide a kid in any request JWTs, or assertion JWTs, that you provide to GOV.UK One Login.

If your service currently shares static keys, you can change to sharing keys through a JWKS endpoint. This change will not require any downtime for your service.

Begin in your test environment.
Deploy your publicly available JWKS endpoint to return your test environment public keys. These must include a kid.
Update your code to include a kid in the JWT headers for both the:
- request JWT you provide in the GET /authorize request. See secure your authorisation request if you’re using a JWT-secured OAuth 2.0 authorisation request (JAR).
- client_assertion JWT your provide in the GET /token request. See create a JWT assertion for more details on the process.
Deploy the updated code for your service to your test environment. GOV.UK One Login will ignore the kid in the header, and will continue to use the STATIC key, until you complete the process by updating your configuration.

Use the GOV.UK One Login admin tool to update the configuration for your test service. This will also specify the use of your exposed test environment JWKS endpoint.

Sign in to the GOV.UK One Login admin tool.
Select your service name to view its configuration.
Scroll to Client Authentication.
Select Change next to Public key.
Select JWKS URL under Select a Key Source.
Add the URL of your test environment JWKS endpoint to get your public keys.
Select Confirm.
Test your updated code in the test environment. You can also test it against the GOV.UK One Login Simulator.

Make the following changes to your production environment:

Deploy a publicly available production JWKS endpoint to return your production public keys. These must include a kid. Also include an entry for the currently configured public keys to avoid downtime when changing to using keys from the JWKS endpoint.
Deploy the updated code for your service to production. GOV.UK One Login will ignore the kid in the header and will continue to use the STATIC key until the configuration has been updated.
Create a request through Live Service Hub to update your production configuration.
Make sure you tell us:
- your client ID
- that you want to change your PublicKeySource to JWKS
- the URL of the production JWKS endpoint that you’ve exposed
GOV.UK One Login will notify you when we update your configuration.
You can now rotate your keys by mangaing the entries on your JWKS endpoint.

Revoke a public key on your JWKS endpoint

GOV.UK One Login caches keys for up to 24 hours.

You should notify GOV.UK One Login if you need to immediately revoke a key from your JWKS endpoint. You can use Live Service Hub to contact GOV.UK One Login to prevent the continued use of compromised keys.

You can configure GOV.UK One Login to use a fixed public key to validate your JWTs using the GOV.UK One Login admin tool.

Sign in to the GOV.UK One Login admin tool.
Click your service name to view its configuration.
Go to Client Authentication.
Select Change next to Public key.
Select STATIC under Select a Key Source.
Add the contents of the file for your private key.
Select Confirm.

This page was last reviewed on 22 August 2024.

Cookies on GOV.UK Sign In

Set up your public and private keys

Create a key pair

Share your public keys with GOV.UK One Login

Share your public keys using a JWKS endpoint

Change how you share your public keys

Revoke a public key on your JWKS endpoint

Share your fixed public key