Verify Service Provider

GOV.UK Verify has closed

This repository is out of date and has been archived

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 disclosure@digital.cabinet-office.gov.uk with details.

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

Licensing

MIT License