Skip to main content
Table of contents

Matching Service Adapter

The Matching Service Adapter (MSA) is a software tool supplied free of charge by the GOV.UK Verify team. It simplifies communication between your Local Matching Service and the GOV.UK Verify Hub.

Set up your MSA

The Matching Service Adapter (MSA) is a software tool supplied free of charge by the GOV.UK Verify team. It simplifies communication between your Local Matching Service and the GOV.UK Verify Hub.

The MSA handles complex matching requirements. We recommend that you use the MSA and always make sure you have the latest version.

You need to host the MSA so the GOV.UK Verify Hub can make requests to it.

If you do not want to use the MSA, contact the GOV.UK Verify team.

To run the Matching Service Adapter (MSA) you need:

  • Java Runtime Environment (JRE) version 8
  • 512 MB to 1 GB of RAM, on top of what you need to run your operating system
  1. Download the latest release of the MSA. It contains:

    • a JAR (Java Archive) file containing the MSA implementation, as well as the trust stores prod_ida_idp_metadata.ts, prod_ida_hub_metadata.ts, test_ida_idp_metadata.ts, and test_ida_hub_metadata.ts
    • a truststore metadata file for non-production environments (the SAML compliance tool and the integration environment) - test_ida_metadata.ts
    • a truststore metadata file for the production environment - prod_ida_metadata.ts
    • a sample YAML configuration file for non-production environments - test-config.yml
    • a sample YAML configuration file for the production environment - prod-config.yml
  2. To extract the files, run the following command::

      unzip verify-matching-service-adapter-[build number].zip


Typically, GOV.UK Verify releases a new version of the MSA every 2 or 3 months. Some releases are essential updates and we may remove support for older versions. To keep updated, contact the GOV.UK Verify support team to ensure you are on the MSA email distribution list.

Get certificates for your MSA

Your MSA needs a signing certificate and an encryption certificate. You must use different certificates for each environment. To obtain certificates:

Generate self-signed certificates for the different environments 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

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 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

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.

Configure your MSA

When you start the MSA, you need to supply a YAML configuration file.

The MSA zip file contains two sample YAML configuration files:

  • test-config.yml for the SAML compliance tool and the integration environment
  • prod-config.yml for the production environment

Adapt the YAML configuration file where required.

 Start the Matching Service Adapter

To start using the MSA, run the following command, supplying the path to your configuration file:

java -jar [filename].jar server [path to configuration file].yml

You can now run by posting the following JSON to the SAML compliance tool:

Content-Type: application/json
    "serviceEntityId":"[entityID for your service - you can use the same URL as the assertionConsumerServiceUrl]",
    "assertionConsumerServiceUrl":"[assertion consumer service URL: this is the URL that will consume responses from the GOV.UK Verify hub]",
    "signingCertificate":"[Base64-encoded X509 signing certificate for your service]",
    "encryptionCertificate":"[Base64-encoded X509 encryption certificate for your service]",
    "expectedPID":"[expected persistent identifier: this is the user id that the MSA returns in an assertion]",
    "matchingServiceEntityId":"[entityID for your MSA]",
    "matchingServiceSigningPrivateKey":"[Base64-encoded private signing key for the MSA, see below]",
    "userAccountCreationAttributes":["optional", "list", "of", "attributes", "the", "government", "service", "requires", "for", "new", "user", "account", "creation", "see", "below"]

To help build your local matching service, you can use the example of the JSON request that the MSA posts to your service.

Error: Signature verification failed

When starting the MSA, you may receive an error message with the phrase ‘signature verification failed’. This is expected behaviour and is logged from a third-party library.

The Verify hub metadata contains multiple signing certificates, but only one private key is in use at a time. The metadata refreshes automatically approximately every 10 minutes.

The MSA checks each of the certificates in turn. The MSA will return ‘Signature verification failed’ if it checks an unused certificate. It will then continue to check each certificate until it finds a valid certificate.


When the MSA is installed in your [integration or production environment][msa-environments], health checks run every 60 seconds to ensure that the MSA is functioning correctly. They test:

  • connectivity
  • that the MSA accepts the hub signature
  • that the hub accepts the MSA signature

Configure HTTP proxies

The MSA supports HTTP and HTTPS proxies configured by Java properties.

For information on configuring HTTPS proxies, refer to the Java documentation.

Connect your MSA to the internet securely

Your MSA must only respond to matching requests from the GOV.UK Verify hub, otherwise there’s a risk of user data being compromised.

The MSA checks that matching service requests are genuine by checking their cryptographic signatures.

To ensure that only the GOV.UK Verify hub can access the MSA, make sure your MSA:

  • is only exposed as HTTPS endpoints
  • only uses strong recent versions of TLS (for example TLS 1.2); turn off obsolete and insecure versions (for example SSLv1, SSLv2, and SSLv3)
  • supports multiple strong cipher suites

    GOV.UK Verify will remove support for TLS cipher suites if serious weaknesses become known. Having multiple suites provides resilience.

  • allows requests and health checks only from the IP addresses of hub services provided by your engagement lead

    Each MSA should communicate with only 1 hub service (SAML compliance tool, integration environment, or production environment).