Matching Service Adapter¶

Caution

This documentation is no longer maintained. View the latest documentation for the Matching Service Adapter..

The Matching Service Adapter (MSA) is a software tool supplied free of charge by GOV.UK Verify. It simplifies communication between your local matching service and the GOV.UK Verify hub.

A matching service is composed of the MSA and a local matching service. Government services host their matching service within their security domain.

For more details, see the diagrams:

GOV.UK architecture

matching cycles

create user accounts

The MSA is a stateless service. It runs on Java 8 using Dropwizard.

Why does GOV.UK Verify use the Matching Service Adapter?¶

The hub uses SAML as its communication method. Government services usually use JSON (JavaScript Object Notation) for their local matching services. A SAML matching service interface is therefore required. The MSA converts SAML into JSON and vice versa. It also performs encryption, decryption, and signing of SAML messages. For more information, see the diagram showing the SAML message flow within the GOV.UK Verify federation.

It can be difficult and expensive to implement a SAML matching service interface. GOV.UK Verify provides the MSA so you can concentrate on the business logic and matching rules for your local matching service.

What do you need to do?¶

We recommend that you use the MSA. If you do not want to, please contact the GOV.UK Verify support team to discuss your alternatives.

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

To use the MSA, you need to:

Build your local matching service – you can use the example of the JSON request that the MSA posts to your service and the JSON schema for a matching request.
Install the Matching Service Adapter.
Configure the Matching Service Adapter.

You will then be able to run SAML compliance tests between the hub and your matching service.

For more information, see Steps to integrate GOV.UK Verify into your service.