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.
For more guidance on the role of a local matching service and how to build one, refer to the:
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
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.