Table of contents

Set up the successful verification user journey

This guide is the first step to integrating your service with the Verify Service Provider (VSP). The VSP allows your service to securely communicate with the GOV.UK Verify Hub without handling SAML.

Find out what is involved in sending requests to and receiving responses from the GOV.UK Verify Hub and how to use the VSP to:

  • generate SAML authentication requests
  • translate SAML responses

The guide uses a GOV.UK Verify-hosted testing service as a placeholder for the GOV.UK Verify Hub. This means you can follow the instructions on this page using your local VSP setup, without any additional backing services.

Before you start

You need VSP 2.0.0 or above to follow instructions on this page. See the latest VSP release on GitHub.

Using the VSP with the testing service

To connect your VSP to the testing service, start the VSP using the development command:

./bin/verify-service-provider development -u localhost:8080

The example sets http://localhost:8080 as the endpoint where the testing service sends the SAML responses.

Read more about the development command and other commands available for the VSP in the VSP’s README file on GitHub.

Send a request

Once a user starts a GOV.UK Verify journey from their browser, your service must send a request to the VSP to generate an authentication request. Your service must send the authentication request to the testing service through the browser. The authentication request is also known as a SAML AuthnRequest.

Vsp request sequence diagram

Generate an authentication request

Make an HTTP POST request to the VSP’s /generate-request endpoint to generate an authentication request message:

> POST /generate-request HTTP/1.1
> Content-Type: application/json

The response from the VSP is in JSON format and contains the authentication request:

{
    "samlRequest": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c2FtbDJwOkF1dGhuUmVxdWVzdCB4bWxuczpzYW1sMnA9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDpwcm90b2NvbCIgRGVzdGluYXRpb249Imh0dHBzOi8vY29tc...",
    "requestId": "_f43aa274-9395-45dd-aaef-25f56f49084e",
    "ssoLocation": "https://compliance-tool-reference.ida.digital.cabinet-office.gov.uk/SAML2/SSO"
}

The parts of the response are:

Field Description
samlRequest Your base64 encoded SAML authentication request
requestId A string that identifies the SAML authentication request
ssoLocation The URL to send the authentication request to, for example the testing service.

Store the requestId

You will need to access the requestId later in the process to link the identities received from GOV.UK Verify with the correct user.

You must store the requestId securely and link it to the user’s session. For example, you could store the requestId in a secure cookie.

Send the authentication request to the testing service

After receiving the authentication request, your service sends that request to the testing service through the browser. To do this, render an HTML form containing JavaScript to auto-submit the form, as described by SAML HTTP Post Binding:

<!-- The form containing the SAML authentication request
to be submitted to the testing service -->
<form method='post' action='${escape(ssoLocation)}'>
  <h1>Continue to next step</h1>
  <p>Because Javascript is not enabled on your browser, you must press the continue button</p>
  <input type='hidden' name='SAMLRequest' value='${escape(samlRequest)}'/>
  <input type='hidden' name='relayState' value=''/>
  <button>Continue</button>
</form>

<!-- JavaScript to automatically submit the form
and POST to `ssoLocation` -->
<script>
  var form = document.forms[0]
  form.setAttribute('style', 'display: none;')
  window.setTimeout(function () { form.removeAttribute('style') }, 5000)
  form.submit()
</script>

Make sure to escape inputs so that special characters are not processed. In our example, we are using the Node.js Express framework’s escape method when rendering the form.

For a consistent user journey it’s recommended you also include page styling that matches your service. If a user has JavaScript disabled, the page they’ll see uses this styling and prompts users to select Continue.

Response from the testing service

After the browser submits the form, the testing service returns a response.

This response contains "status": "PASSED" and a responseGeneratorLocation URL which you can use to access the test scenarios:

  {
    "status": {
      "status": "PASSED",
      "message": null
    },
    "responseGeneratorLocation": "https://compliance-tool-reference.ida.digital.cabinet-office.gov.uk:443/rp-test/_5178cb11-bc5a-4124-8c61-f8bac98e1db6"
  }

If the status is not PASSED, you may need to restart the VSP using the development command.

Handle a response

Your service needs to be able to receive an HTML form containing the SAML response. The testing service sends the form through the browser. After receiving the form, your service translates the SAML response into JSON using the VSP. Depending on the scenario in the SAML message, your service should offer appropriate messaging to help the user continue.

Vsp response sequence diagram

Run the IDENTITY_VERIFIED response scenario

Using the response you got from the testing service, go to the URL in responseGeneratorLocation using your browser. The JSON response contains objects with the test cases or scenarios your service must handle when it’s live.

To simulate a user having their identity successfully verified, use the following test case:

{
  "executeUri" : "https://compliance-tool-reference.ida.digital.cabinet-office.gov.uk:443/rp-test/_6817b389-4924-479c-9851-db089c4e639c/test-non-matching/10",
  "id" : 10,
  "title" : "IDENTITY_VERIFIED",
  "description" : "Issues a successful response where the user has been successfully verified."
},

Several parameters describe each scenario:

Parameter Description
executeUri URI for running the test scenario
id Number identifying the scenario
title The name of the scenario
description Details about the scenario

The responseGeneratorLocation and executeUri are only valid for the VSP session that generated them. The VSP generates a new set of keys for the testing service every time you start the VSP with the development command, which leads to the URLs changing.

If the responseGeneratorLocation or executeUri you generated do not work, restart your VSP. The GOV.UK Verify team occasionally restarts the testing service, which clears the current testing session. Restarting your VSP restores the connection with the testing service.

Receive the SAML response from the testing service

Visiting the executeUri for the IDENTITY_VERIFIED scenario causes the testing service to generate a SAML response for this scenario.

The testing service sends the SAML response inside an HTML form, through the browser. The SAML response is base64 encoded within the SAMLResponse form parameter:

SAMLResponse=PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHNhbWwycDpSZXNwb25zZSBEZXN0aW5hdGlvbj0iaHR0cHM6Ly9wYXNzcG9ydC12ZXJpZnktc3R1Yi1yZWx5aW5nLXBhcnR5LWRldi5jbG91ZGFwcHMuZGlnaXRhbC92ZXJpZnkv...

Your service receives the form at the endpoint provided when starting the VSP.

Request to translate the SAML response

To translate the SAML response into JSON, make an HTTP POST request to the VSP’s /translate-response endpoint:

> POST /translate-response HTTP/1.1
> Content-Type: application/json
>
{
  "samlResponse" : "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c2FtbDJwOkF1dGhuUmVxdWVzdCB4bWxuczpzYW1sMnA9InVybjpvYXNpczpuYW1lczp0YzpTQU1MOjIuMDpwcm90b2NvbCIgRGVzdGluYXRpb249Imh0dHBzOi8vY29tc...",
  "requestId" : "_64c90b35-154f-4e9f-a75b-3a58a6c55e8b",
  "levelOfAssurance" : "LEVEL_2"
}

The request body must contain:

Parameter Description
samlResponse Base64 encoded SAML response from the testing service
requestId The string your saved in a secure cookie when generating
the authentication request
levelOfAssurance The level of assurance for your service

Handle the translated response from the VSP

An HTTP 200 OK response confirms the VSP translated the SAML response successfully. The response body contains:

> HTTP/1.1 200 OK
> Content-Type: application/json
>
{
    "scenario": "IDENTITY_VERIFIED",
    "pid": "etikgj3ewowe",
    "levelOfAssurance": "LEVEL_2",
    "attributes": {...}
}

For a successful verification journey, the response body contains:

Parameter Description
scenario The name of the response scenario
pid A unique identifier for a user
levelOfAssurance The level of assurance the user verified at
attributes Information about the user’s identity

Your service can use this identity dataset to guide a user with their service journey.

Next Steps

Now that your service can handle the successful verification user journey, make sure your service can handle possible failure scenarios.

Find out more about the VSP API from:

This page was last reviewed on 14 February 2019. It needs to be reviewed again on 14 May 2019 by the page owner #verify-developers .
This page was set to be reviewed before 14 May 2019 by the page owner #verify-developers. This might mean the content is out of date.