Matching Service Adapter signing
If your connection to GOV.UK Verify involves a Matching Service Adapter (MSA), you are responsible for keeping its encryption and signing certificates up to date.
You must update the certificates containing your MSA’s public keys before they expire. If you do not, your users will not be able to access your service using GOV.UK Verify.
Rotate your MSA signing key and certificate
Step 1. Create a new self-signed signing 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 DER encoded.
The self-signed certificate must be:
- valid for one year
- in X.509 format and PEM encoded
The terminal will prompt you for information. You must provide a The There is no mandatory naming convention for For example, the common name could be
See an example
# generate your key and self-signed certificate
openssl req -x509 -newkey rsa:2048 -days 365 -nodes -sha256 \
-keyout <private-key>.key -out <certificate>.crt
# convert your MSA key to use DER encoding
openssl pkcs8 -topk8 -nocrypt \
-in <private-key>.key -out <private-key>.pk8 -outform DER
Common Name. All other information is optional.
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.
Common Name, but it’s useful during troubleshooting if you include the:
Common Name must not contain underscores.
The terminal will prompt you for information. You must provide a
There is no mandatory naming convention for
For example, the common name could be
Step 2. Add the new signing key and certificate to your MSA configuration
Add your new signing key and self-signed certificate to
signingKeys.secondary in your MSA configuration.
Restart the MSA to implement the configuration changes.
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
||The name of the
||A meaningful name for your certificate which is published in your MSA’s metadata|
||The name of the
Restarting the MSA publishes the new signing certificate to the MSA’s metadata. The service provider you’re using reads this metadata and uses the MSA’s signing certificate to trust assertions signed by the MSA.
Step 3. Upload the new signing certificate
Upload your new signing certificate to the GOV.UK Verify Manage certificates service.
This starts a deployment process that adds your new MSA signing certificate to 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 both your new and your old certificate to check the signature on messages coming from your service.
The deployment process takes approximately 10 minutes. You will receive an email confirmation when the GOV.UK Verify Hub starts using your new signing certificate. You can also check the deployment status on the GOV.UK Verify Manage certificates service dashboard.
Wait for deployment confirmation before moving to the next step.
Step 4. Delete the old MSA signing key and certificate
Before deleting the old key and certificate, make sure:
- you’ve received deployment confirmation from the GOV.UK Verify Team
- your service provider is using your new MSA signing certificate
If you’re using the VSP, you can check its logs to confirm the VSP refreshed its metadata. Once it has loaded the new MSA metadata, the VSP is using your new MSA signing certificate to trust messages from your MSA.
The email from the GOV.UK Verify team confirms that GOV.UK Verify Hub is using your new MSA signing certificate to trust messages signed with your new MSA signing key. This means you can replace the old signing key from your MSA configuration.
To remove the old signing key from the MSA configuration:
- Delete the
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.
Your service provider now trusts assertions signed with your new MSA signing key.
Step 5. Remove your old certificate from the GOV.UK Verify Hub configuration
To make sure the GOV.UK Verify Hub does not trust messages signed with your old key, you must also remove your old certificate from the GOV.UK Verify Hub configuration.
- Go to the GOV.UK Verify Manage certificates service dashboard.
- Select the MSA signing certificate due to expire.
- Select Stop using this certificate.
The GOV.UK Verify Hub now only trusts messages signed with your new MSA signing key.