Skip to main content
Table of contents

Service provider without dual running

If you built your own service provider to connect to GOV.UK Verify, you are responsible for keeping its encryption and signing certificates up to date.

Because your service provider does not support dual running for your encryption keys, there will be a small outage when you update the encryption key. To minimise disruption to your users, it’s recommended you do the update during periods of low traffic for your service.

If you’re using the Verify Service Provider, see how to update your Verify Service Provider keys.

Rotate your service provider encryption key and certificate

Step 1. Create a new self-signed encryption certificate

Use your preferred method to generate a new private key and self-signed certificate pair.

Make sure the private key is PKCS #8 formatted and PEM encoded.

The self-signed certificate must be:

  • valid for one year
  • in X.509 format and PEM encoded

See an example
You can use OpenSSL to generate your keys and self-signed certificates. Most Linux distributions and Mac OS versions have OpenSSL installed.

Generate your private key and self-signed certificate:

openssl req -x509 -newkey rsa:2048 -days 365 -nodes -sha256 \
   -keyout <private-key>.key -out <certificate>.crt

The terminal will prompt you for information. You must provide a Common Name. All other information is optional.

The Common Name is the part of the certificate metadata that helps you identify that certificate more easily. You can use the Common Name to check you’ve uploaded the right certificate when using the GOV.UK Verify Manage certificates service.

There is no mandatory naming convention for Common Name, but it’s useful during troubleshooting if you include the:

  • name of your service
  • name of the component the certificate is for
  • environment name you generated the certificate for
  • certificate type
  • version number for your certificate

Common Name must not contain underscores.

For example, the common name could be Universal-Credit-MSA-integration-signing-01.

Step 2. Upload the new encryption certificate

Upload your new encryption certificate to the GOV.UK Verify Manage certificates service.

This starts a deployment process to replace your old service provider encryption certificate with the new one in the GOV.UK Verify Hub configuration. During deployment the GOV.UK Verify Hub will continue to use your old certificate. The deployment process does not cause any connection downtime.

When the deployment is complete, the GOV.UK Verify Hub will be using your new certificate to encrypt messages for your service.

This will break your connection to GOV.UK Verify. Your connection will remain broken until you replace your old encryption key with the new one in Step 3.

Warning Your connection to GOV.UK Verify will break once your new encryption certificate finishes deploying to the GOV.UK Verify Hub. Restore your connection in the next step.

The deployment process takes approximately 10 minutes. You will receive an email confirmation when the GOV.UK Verify Hub starts using your new encryption certificate. You can also check the deployment status on the GOV.UK Verify Manage certificates service dashboard.

Step 3. Replace the old encryption key

Replace your old service provider private encryption key with the new one.

Your connection to GOV.UK Verify is restored once your new service provider encryption key is live.

Once your new encryption key is live, your service provider will be using it to decrypt messages from GOV.UK Verify Hub.

This page was last reviewed on 27 January 2020. It needs to be reviewed again on 27 May 2020 by the page owner #verify-developers .
This page was set to be reviewed before 27 May 2020 by the page owner #verify-developers. This might mean the content is out of date.