Verify Service Provider
The Verify Service Provider (VSP) generates and translates Security Assertion Markup Language (SAML) messages to and from the GOV.UK Verify Hub. SAML is an open standard for secure message exchange which GOV.UK Verify uses when handling information about identities.
Using the VSP removes the need for services to handle SAML by:
- generating SAML requests to send to the GOV.UK Verify Hub
- translating SAML responses from the GOV.UK Verify Hub into JSON
Services will need to host the VSP on their own infrastructure.
The VSP allows you to:
- handle signing and encryption key rotation without service downtime.
- connect multiple services to GOV.UK Verify using the same VSP deployment
See also:
- Technical documentation for connecting services
- Setting up the VSP
- VSP API reference documentation
- OpenAPI v3 VSP API specification
Setup
Prerequisites
To use the Verify Service Provider, we recommend you use Java 11 or a long-term supported version of Java 8.
Download
Download your own copy of the Verify Service Provider.
Get started
GOV.UK Verify provides prebuilt clients for the following languages and frameworks:
| Language / Framework | Client Library |
|---|---|
| node js / passport.js | passport-verify |
If you're building or setting up your own client for the VSP, see the technical documentation on how to get started with the VSP.
See the API reference for full details of the API.
Run
You can run the the VSP using several commands, depending on your development needs:
| Command | Use case |
|---|---|
development |
Local development of a VSP client The VSP is connected to a testing service hosted by the GOV.UK Verify team. |
server |
End-to-end testing and running in production The VSP uses the configuration provided to connect to a full-scale deployment of the GOV.UK Verify Hub. |
check |
Validates your configuration file. |
development
You can use the development command if you're building your own client for the VSP. The command starts the VSP connected to a testing service hosted by the GOV.UK Verify team. The testing service acts as a placeholder for the GOV.UK Verify Hub. This means you can use your local setup to test if your service can respond appropriately to all possible scenarios in a Verify journey.
When running the VSP using the development command, it initialises the testing service by:
- generating its self-signed keys and certificates
- adding the keys and certificates to the VSP configuration
- setting the testing service environment in the VSP configuration
- initialising a testing session with the testing service
To start the VSP connected to the testing service, run:
./bin/verify-service-provider development
You can use the following command line options to customise the behaviour of the development command:
| Option | Description | Default |
|---|---|---|
-d IDENTITYDATASET or --identityDataset IDENTITYDATASET |
The identity dataset the testing service will use | Test identity dataset |
-u URL or--url URL |
The URL where the testing service will send responses | http://localhost:8080/SAML2/Response |
-t TIMEOUT or--timeout TIMEOUT |
The timeout in seconds when communicating with the testing service | 5 |
-p PORT or--port PORT |
The port the service will use | 50300 |
--host BINDHOST |
The host the service will bind to | 0.0.0.0 |
You can check the application is running by calling the healthcheck endpoint with:
curl localhost:{$PORT}/admin/healthcheck
For more information on building your own client using the development command, see the technical documentation on how to get started.
server
Use the server command when running the VSP in an environment containing a full-scale deployment of the GOV.UK Verify Hub, for example the Integration or Production environments.
To run the VSP using the environment and security configuration in verify-service-provider.yml, export your environment variables and run:
./bin/verify-service-provider server verify-service-provider.yml
The application will write logs to STDOUT.
You can check the application is running by calling the healthcheck endpoint with:
curl localhost:{$PORT}/admin/healthcheck
check
You can run the VSP with the check command to confirm that your configuration file is valid. For example, to check that verify-service-provider.yml is valid, run:
./bin/verify-service-provider check verify-service-provider.yml
Configure
The VSP comes with a default YAML configuration file
called verify-service-provider.yml which you can customise either by providing environment variables or by editing the file directly.
By default the following environment variables are supported:
| Variable | Description |
|---|---|
VERIFY_ENVIRONMENT |
The GOV.UK Verify Hub environment to run in. For example PRODUCTION, INTEGRATION |
SERVICE_ENTITY_IDS |
A JSON string array with the service's entity ID, for example '["http://entity-id"]'. If you have several services using one VSP deployment,the array should contain all of their service entity IDs. |
SAML_SIGNING_KEY |
A base64 encoded RSA private key used for signing the request to GOV.UK Verify Hub. |
SAML_PRIMARY_ENCRYPTION_KEY |
A primary base64 encoded PKCS8 RSA private key used to decrypt SAML responses. |
SAML_SECONDARY_ENCRYPTION_KEY |
(Optional - default empty) A secondary base64 encoded PKCS8 RSA private key is used to decrypt SAML responses. This parameter applies during key rotation events. |
PORT |
(Optional - default 50400) The TCP port where the application will listen for HTTP traffic |
LOG_LEVEL |
Optional - default INFO) The threshold level for logs to be written, for example DEBUG, INFO, WARN, or ERROR) |
If you are using the legacy setup involving a Matching Service Adapter (MSA), additional environment variables apply. Contact the Verify team if you need to use the MSA with VSP 2.0.0 or above.
The VSP is a Dropwizard application, so you can also configure it with the options provided by Dropwizard. Check the VSP release notes to find out which Dropwizard version was used when building the release you're using.
Contribute to the Verify Service Provider
If you wish to contribute to the development of the VSP then follow the development guide.
Support and raising 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.