Example local matching service for GOV.UK Verify

This is an example local matching service built by the GOV.UK Verify team to demonstrate how a local matching service works and help services building their own. Every government service connecting to Verify must build a local matching service.

⚠️ This is an example implementation and is not production-ready. ⚠️

For more guidance on the role of a local matching service and how to build one, refer to the:

• Verify technical guide
• development stories for this example

Background

This example uses a simple database and matching strategy. It has not been designed to be used in front of a real database.

See the examples folder for example matching datasets.

Database

This example local matching service uses a SQL database. Refer to the database schema for details.

All SQL has been written for Postgres and has not been tested with any other engine.

Matching strategy

This example implementation follows a simplified matching strategy from DWP.

The example uses the following attributes:

• firstname
• surname
• date of birth
• postcode
• National Insurance number

Matching cycles

This example follows Cycle 0, Cycle 1 and Cycle 3 match cycles.

It will first run Cycle 0. The Matching Service Adapter will provide a hashed persistent identifier (PID). The cycle will then check the PID can be matched to an existing PID in the database. This cycle only works if the user has previously verified their identity with the same identity provider.

If Cycle 0 fails, it will run Cycle 1 using surname and date of birth. The example will disambiguate similar matches with postcode and then firstname. All four attributes need to match in order to return match.

If the request contains a National Insurance number, the example will run Cycle 3. Using National Insurance number as a Cycle 3 attribute was an arbitrary decision for the purposes of this example. When building your own local matching service, you should use other attributes.

If the example finds a match in Cycles 1 or 3 it will store the PID in the database.

Caveats

This example local matching service searches for matches through all address and surnames in the database regardless of their history.

It will only return match or no match. It does not provide any fuzzy matching, for example matching ONeill to O'Neill or Will to William. The example does not provide any means of logging or investigating results.

The example ignores any attributes where verified is set to false. This would be a suitable starting point for any service with an existing dataset expected to include most new users.

The example is not case sensitive and will remove any spaces in requests containing postcodes.

Run

⚠️ This is an example implementation and is not production-ready. Contact the Verify team if you'd like any support with your matching strategy or local matching service. ⚠️

Prerequisites

To run the example local matching service locally, you'll need:

• Java 8
• Docker
• working version of Verify Matching Service Test Tool

Build

To start the matching service without a clean database, run

./gradlew installDist

Then execute

DB_URI="replace_with_actual_database_url" build/install/verify-local-matching-service-example/bin/verify-local-matching-service-example 

To start the matching service with a clean postgres database, run

docker-compose run -e DB_URI="jdbc:postgresql://db:5432/postgres?user=postgres" app ./gradlew run 

Configuration

You can configure the local matching service using environment variables or Command Line arguments.

Environment variables

PORT - port to start matching service on (default is 50500)
LOG_LEVEL - logging level for matching service (default is INFO) - can be (DEBUG, INFO, WARNING, ERROR) going down in verbosity from left -> right
DB_URI - JDBC connection URI to database to run migrations and connect to. Format is “jdbc:postgresql://host-name:port/database-name?user=user-name&password=password”

Command line arguments If you don't want to use the default config file or environment variables, you can specify the location of the config file using ./bin/verify-local-matching-service-example server /path/to/config.yml

Testing

You can run:

• unit and integration tests with gradle
• specific local matching service test tool tests

To run all tests:

./pre-commit.sh

For unit and and integration tests only

./gradlew test intTest

For Matching service tests only

The Verify Matching Service Test Tool helps you check your local matching service can:

• handle matching datasets
• find and match records correctly
• handle matching failures

You can use the test tool while building your local matching service and include it any automated testing.

This example uses the test tool. See the examples folder for example tests.

Support and raising issues

Contact the Verify team if you'd like any support with your matching strategy or local matching service via [email protected].

Security issues

If you think you have discovered a security issue in this code please email [email protected] with details.

For non-security related bugs and feature requests please raise an issue in the GitHub issue tracker.

Licensing

MIT License