Rotate your encryption and signing keys¶

When the certificates containing your public keys are due to expire, you must rotate your keys. This allows you to introduce a new set of keys and certificates with no service interruption.

As a government service you are responsible for maintaining the encryption and signing keys for your Matching Service Adapter (MSA) and your service provider. Your service provider could be the Verify Service Provider (VSP) or another service provider.

Before you start rotating keys, you must get new signed certificates for your public keys from the IDAP certificate authority.

Then, as part of the key rotation process, you must rotate your:

MSA encryption key
MSA signing key
VSP encryption key or service provider encryption key
VSP signing key or service provider signing key

To communicate with the GOV.UK Verify team during a key rotation process, send an email to idasupport+onboarding@digital.cabinet-office.gov.uk. This will begin an email thread that you can use for any queries you have during this key-rotation process.

Get new signed certificates¶

Generate new signing and encryption private keys for both the MSA and your service provider - this is 4 keys in total.
Generate a certificate signing request for each of the the keys you generated in step 1.
Submit the certificate signing requests from step 2 to the IDAP certificate authority.

The IDAP certificate authority will issue you signed certificates for the MSA and your service provider encryption and signing public keys.

Rotate your MSA encryption key¶

Add a second list item containing the details for your new public and private key under encryptionKeys in your MSA configuration, for example:

encryptionKeys:
- publicKey:
    certFile: msa_encryption_2016.crt
    name: MSA Encryption 2016
  privateKey:
    keyFile: msa_encryption_2016.pk8
- publicKey:
    certFile: msa_encryption_2017.crt
    name: MSA Encryption 2017
  privateKey:
    keyFile: msa_encryption_2017.pk8

Restart the MSA to implement the configuration changes - the MSA can now use both the new and old keys to decrypt SAML messages.

Note

While both keys are in use, you may see error messages in the logs with the description Unwrapping failed. These messages appear because the MSA attempts to decrypt the SAML message using each key in turn. You can safely ignore these messages. However, do not ignore any other error messages related to SAML decryption.

Send the new certificate to the GOV.UK Verify team and wait for the team to confirm deployment.
After the GOV.UK Verify team confirm they have deployed the new public encryption key, delete the old private encryption key and certificate.
Restart the MSA to implement the configuration changes.

The MSA now uses the new encryption key to decrypt SAML messages, and the GOV.UK Verify hub now uses the new key to encrypt SAML messages for your service.

Rotate your MSA signing key¶

The MSA publishes its certificates containing the public keys in its own metadata at run time. The service provider you’re using reads this metadata and uses the MSA’s signing certificate to trust assertions signed by the MSA. Therefore you must restart the MSA once you’ve changed the certificates in the configuration file (step 2) and make sure your service provider has read the new metadata (step 3).

Send the new signing certificate to the GOV.UK Verify team and add it to the MSA configuration under signingKeys.secondary, for example:

signingKeys:
  primary:
    publicKey:
      certFile: msa_signing_2016.crt
      name: 2016 MSA Signing Key
    privateKey:
      keyFile: msa_signing_2016.pk8
  secondary:
    publicKey:
      certFile: msa_signing_2017.crt
      name: 2017 MSA Signing Key
    privateKey:
      keyFile: msa_signing_2017.pk8

Restart the MSA to publish the new signing certificate to its metadata.
Make sure your service provider has read the new metadata.

If you’re using the VSP, wait for it to load the MSA metadata. The VSP periodically refreshes its metadata and will log when it has finished. Once it loads the new metadata, the VSP trusts assertions signed with the new MSA signing key.

Delete the signingKeys.primary section and rename signingKeys.secondary to signingKeys.primary - the MSA now signs the assertions with the new key.
Restart the MSA to update its metadata to contain only the new signing certificate.
Inform the GOV.UK Verify team that the new key is live.

Your service provider now trusts assertions signed with your new MSA signing key.

Rotate your VSP encryption key¶

These instructions apply to you if you’re using the Verify Service Provider (VSP).

Add the new VSP private encryption key you’ve generated to the samlSecondaryEncryptionKey field in the VSP configuration.
Restart the VSP to implement the configuration changes - the VSP can now use both the new and old keys to decrypt SAML messages.
Send the new certificate to the GOV.UK Verify team and wait for the team to confirm deployment.
After receiving confirmation from the GOV.UK Verify team, replace the key in samlPrimaryEncryptionKey with the key from samlSecondaryEncryptionKey and leave samlSecondaryEncryptionKey empty for the next key rotation.
Restart the VSP to implement the configuration changes.

Your service now uses the new VSP encryption key to decrypt SAML messages.

Rotate your VSP signing key¶

These instructions apply to you if you’re using the Verify Service Provider.

Send your new signing certificate to the GOV.UK Verify team and wait for deployment confirmation.
Replace the old signing key under samlSigningKey in the VSP configuration with the new key.
Restart the VSP to implement the configuration changes - the VSP now signs SAML messages with the new key.
Inform the GOV.UK Verify team that new key is live - the GOV.UK Verify team will remove the old certificate from the GOV.UK Verify hub.

The GOV.UK Verify hub now trusts SAML messages signed with your new VSP signing key.

Rotate your service provider encryption key¶

These instructions apply to you if you’re using an alternative to the Verify Service Provider.

Add your new service provider private encryption key to your service endpoint - your service can now use both the new and old keys to decrypt SAML messages.
Send the new certificate to the GOV.UK Verify team and wait for the team to confirm deployment.
After receiving confirmation from GOV.UK Verify team, remove the old encryption key from your service endpoint.

Your service provider now uses the new encryption key to decrypt SAML messages.

Rotate your service provider signing key¶

These instructions apply to you if you’re using an alternative to the Verify Service Provider.

Send your new signing certificate to the GOV.UK Verify team and wait for deployment confirmation.
Replace the old private signing key with the new key on your service endpoint - your service provider now signs SAML messages with the new key.
Inform the GOV.UK Verify team that the new key is live - the GOV.UK Verify team removes the old certificate from the GOV.UK Verify hub.

The GOV.UK Verify hub now trusts SAML messages signed with your new service provider signing key.