Skip to main content
Table of contents

Connecting to Verify with a compulsory matching service

Local development phase

Prerequisites:

  • choose a product and framework to integrate your service with GOV.UK Verify
  • decide how to store and manage keys and certificates so you can rotate your keys when needed Note

You only need to deploy your code to a server at the end of the development phase, when you test your matching service with the SAML compliance tool. You can do all development steps until this point on a development machine.

Set up the Matching Service Adapter for the SAML compliance tool.

To do this:

  1. Download and install the Matching Service Adapter.
  2. Generate self-signed certificates for the SAML compliance tool. Use your preferred method to generate a new private key and self-signed certificate pair.

Make sure the private key is PKCS #8 formatted and DER encoded.

The self-signed certificate must be:

  • valid for one year
  • in X.509 format and PEM encoded

See an example
You can use OpenSSL to generate your keys and self-signed certificates. Most Linux distributions and Mac OS versions have OpenSSL installed.

# generate your key and self-signed certificate
openssl req -x509 -newkey rsa:2048 -days 365 -nodes -sha256 \
   -keyout <private-key>.key -out <certificate>.crt

# convert your MSA key to use DER encoding
openssl pkcs8 -topk8 -nocrypt \ 
   -in <private-key>.key -out <private-key>.pk8 -outform DER

The terminal will prompt you for information. You must provide a Common Name. All other information is optional.

The Common Name is the part of the certificate metadata that helps you identify that certificate more easily. You can use the Common Name to check you’ve uploaded the right certificate when using the GOV.UK Verify Manage certificates service.

There is no mandatory naming convention for Common Name, but it’s useful during troubleshooting if you include the:

  • name of your service
  • name of the component the certificate is for
  • environment name you generated the certificate for
  • certificate type
  • version number for your certificate

Common Name must not contain underscores.

For example, the common name could be Universal-Credit-MSA-integration-signing-01.

Configure the Matching Service Adapter for the SAML compliance tool.

Outcome: you can start building your service.

For more information, see Install and configure the Matching Service Adapter.

Build a local matching service.

To do this:

  1. Define your matching strategy with your service manager.
  2. Use the example JSON matching request and the JSON schema to help build your local matching service.

Outcome: your service can match users’ verified identities to your data sources.

For more information, see Build a matching service.

Build a service that produces and consumes SAML.

To do this:

  1. Connect your service to the Matching Service Adapter metadata.
  2. Send an authentication request to the GOV.UK Verify hub.
  3. Handle the SAML response from the GOV.UK Verify hub .

Outcome: you’re ready to run SAML compliance tests.

For more information, see How SAML works with GOV.UK Verify and the Identity Assurance Hub Service SAML 2.0 Profile.

Run SAML compliance tests.

To do this:

  1. Test your service with the SAML compliance tool.
  2. Test your matching service with the SAML compliance tool.

Outcome: your service and matching service can consume and produce valid SAML.

For more information, see How SAML works with GOV.UK Verify.

Development in the Integration environment

Request access to the integration environment.

To do this:

  1. Generate self-signed certificates for the integration environment.
  2. Request access to an environment.

Outcome: you’re ready to connect the Matching Service Adapter and your service to the integration environment. For more information, see GOV.UK Verify environments and How a PKI works.

Connect the Matching Service Adapter and your service to the integration environment.

To do this:

  1. Download and install the Matching Service Adapter.
  2. Configure the Matching Service Adapter for the integration environment.

Outcome: you’re ready to run end-to-end testing with test users.

For more information, see Install and configure the Matching Service Adapter and GOV.UK Verify environments.

Run end-to-end testing of all your user journeys in the integration environment.

To do this:

  1. Set up authentication to manage test users.
  2. Create test users.
  3. Run end-to-end tests.

Outcome: your service can handle all the possible outcomes of end-to-end user journeys.

For more information, see GOV.UK Verify environments.

Request access to the production environment.

To do this:

Generate self-signed certificates for the production environment. Use your preferred method to generate a new private key and self-signed certificate pair.

Make sure the private key is PKCS #8 formatted and DER encoded.

The self-signed certificate must be:

  • valid for one year
  • in X.509 format and PEM encoded

See an example
You can use OpenSSL to generate your keys and self-signed certificates. Most Linux distributions and Mac OS versions have OpenSSL installed.

# generate your key and self-signed certificate
openssl req -x509 -newkey rsa:2048 -days 365 -nodes -sha256 \
   -keyout <private-key>.key -out <certificate>.crt

# convert your MSA key to use DER encoding
openssl pkcs8 -topk8 -nocrypt \ 
   -in <private-key>.key -out <private-key>.pk8 -outform DER

The terminal will prompt you for information. You must provide a Common Name. All other information is optional.

The Common Name is the part of the certificate metadata that helps you identify that certificate more easily. You can use the Common Name to check you’ve uploaded the right certificate when using the GOV.UK Verify Manage certificates service.

There is no mandatory naming convention for Common Name, but it’s useful during troubleshooting if you include the:

  • name of your service
  • name of the component the certificate is for
  • environment name you generated the certificate for
  • certificate type
  • version number for your certificate

Common Name must not contain underscores.

For example, the common name could be Universal-Credit-MSA-integration-signing-01.

Fill in the ‘Request access to an environment‘ form.

Outcome: you’re ready to connect the Matching Service Adapter and your service to the production environment.

For more information, see GOV.UK Verify environments and How a PKI works.

Connect the Matching Service Adapter and your service to the production environment.

To do this:

  1. Download and install the Matching Service Adapter.
  2. Configure the Matching Service Adapter for the production environment.

Outcome: your service is ready to go live.

For more information, see Install and configure the Matching Service Adapter and GOV.UK Verify environments.

Maintenance

Rotate your keys.

When the certificates containing your public keys are due to expire, replace your keys and certificates.

Outcome: the encryption and signing certificates for your service and Matching Service Adapter are up to date.

For more information, see How a PKI works.