Skip to main content
Table of contents

Handling failure scenarios

By default, the GOV.UK Verify Hub handles the 2 following possible failure scenarios:

  • if an identity provider cannot verify the user’s identity, the GOV.UK Verify Hub redirects the user to an error page
  • if the session ends before the user completes the journey, the GOV.UK Verify Hub redirects the user to a page containing a link back to your service start page

If your service needs to handle these scenarios in a different way, you must request to be sent failure responses from the GOV.UK Verify Hub. Failure responses tell your service which failure scenario your user has encountered, and allow you to customise your user journey.

Before you start customising

To follow instructions on this page, you must have already:

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.

This guide continues from the ‘Response from the testing service’ section.

Failure scenario responses

There are 2 scenarios when the user does not successfully complete the verification journey.

If the identity provider cannot verify the user’s identity, GOV.UK Verify Hub sends an AUTHENTICATION_FAILED response.

If the session ends before the user completes the verification journey, GOV.UK Verify Hub sends a NO_AUTHENTICATION response.

To get the failure responses from the GOV.UK Verify Hub in the Integration or Production environments, you must contact the GOV.UK Verify team.

Run the scenario

  1. Submit an authentication request to the testing service.
  2. Go to the responseGeneratorLocation URL in the response from the testing service.
  3. Select the executeUri for the AUTHENTICATION_FAILED or NO_AUTHENTICATION scenario.

This is an example of a AUTHENTICATION_FAILED JSON object:

{
  "executeUri" : "https://compliance-tool-reference.ida.digital.cabinet-office.gov.uk:443/rp-test/_6817b389-4924-479c-9851-db089c4e639c/test-non-matching/10",
  "id" : 14,
  "title" : "AUTHENTICATION_FAILED",
  "description" : "The identity provider could not verify the user's identity."
},

This is an example of a NO_AUTHENTICATION JSON object:

{
  "executeUri" : "https://compliance-tool-reference.ida.digital.cabinet-office.gov.uk:443/rp-test/_6817b389-4924-479c-9851-db089c4e639c/test-non-matching/10",
  "id" : 12,
  "title" : "NO_AUTHENTICATION",
  "description" : "The session ended before the user completed the verification journey."
},

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 AUTHENTICATION_FAILED or NO_AUTHENTICATION scenario causes the testing service to generate a SAML response for that 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.

The testing service generates these responses. To get the failure responses from the GOV.UK Verify Hub in the Integration or Production environments, you must contact the GOV.UK Verify team.

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 fields in the request body are:

Field Description
samlResponse Base64 encoded SAML response from the testing service
requestId The string you saved 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 for a AUTHENTICATION_FAILED scenario contains:

> HTTP/1.1 200 OK
> Content-Type: application/json
>
{
    "scenario": "AUTHENTICATION_FAILED"
}

The response body for a NO_AUTHENTICATION scenario contains:

> HTTP/1.1 200 OK
> Content-Type: application/json
>
{
    "scenario": "NO_AUTHENTICATION"
}

When the translated SAML response contains the AUTHENTICATION_FAILED or NO_AUTHENTICATION scenario, your service should send the user to the next page in your service journey.

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