Table of contents

Handle failure scenarios

After setting up the successful verification journey, you should make sure your service can handle the failure scenarios.

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

Scenario Description
NO_AUTHENTICATION The user chose to cancel at some point in their journey.
AUTHENTICATION_FAILURE The identity provider could not verify the user’s identity.

Find out how to handle these failure scenarios, including how to:

  • recognise failure responses
  • respond to users whose identity was not verified

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

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

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

NO_AUTHENTICATION scenario

If a user cancels before the identity verification process is complete, GOV.UK Verify Hub sends a NO_AUTHENTICATION response.

Run the NO_AUTHENTICATION 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 NO_AUTHENTICATION scenario.

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 user chose to cancel at some point in their 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 NO_AUTHENTICATION 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 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 contains:

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

When the translated SAML response contains the NO_AUTHENTICATION scenario, your service should redirect the user to a page offering them other ways to use your service. This could be another way of proving their identity online or in person.

AUTHENTICATION_FAILURE scenario

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

Run the NO_AUTHENTICATION 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_FAILURE scenario.

This is an example of a AUTHENTICATION_FAILURE 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_FAILURE",
  "description" : "The identity provider could not verify the user's identity."
},

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_FAILURE 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 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 contains:

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

When the translated SAML response contains the AUTHENTICATION_FAILURE scenario, your service should redirect the user to a page offering them other ways to use your service. This could be another way of proving their identity online or in person.

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