Merge pull request #192 from govuk-one-login/return-codes-guidance

uploads guidance on return codes

source/before-integrating/choose-which-user-attributes-your-service-can-request.html.md.erb

@@ -45,6 +45,10 @@ You can find details of the claims in the following table.
 | `https://vocab.account.gov.uk/v1/passport`             | This claim contains your user's passport details if GOV.UK One Login proved their identity using their passport.<br><br>If GOV.UK One Login did not prove your user’s identity using their passport, the authorisation response will not return this claim.                                            |
 | `https://vocab.account.gov.uk/v1/drivingPermit`        | This claim contains your user's driving licence details if GOV.UK One Login proved their identity using their driving licence.<br><br>If GOV.UK One Login did not prove your user’s identity using their driving licence, the authorisation response will not return this claim.                       |
 | `https://vocab.account.gov.uk/v1/socialSecurityRecord` | This claim contains your user's National Insurance number if GOV.UK One Login proved their identity using their National Insurance number.<br><br>If GOV.UK One Login did not prove your user’s identity using their National Insurance number, the authorisation response will not return this claim. |
+| `https://vocab.account.gov.uk/v1/returnCode`           | This claim gives information about any issues with the evidence your user provided to prove their identity, for example, if GOV.UK One Login was not able to prove your user’s identity. This will display as a letter code, for example `[{"code": "C"}]`, in the response. <br><br> For security reasons, you’ll have to contact GOV.UK One Login on [[email protected]](mailto:[email protected]) for more detailed information on what issue each return code represents. 
+
+<br><br>
+If you do not include this claim in your request, GOV.UK One Login returns an `access_denied` error instead. |
 
 You can see more about the structure of this information when you [prove your user’s identity](integrate-with-integration-environment/prove-users-identity).
 

source/integrate-with-integration-environment/authenticate-your-user.html.md.erb

@@ -212,7 +212,7 @@ Location: https://YOUR_REDIRECT_URI?error=invalid_request
 | `unsupported_response_type` | Your service is not registered for the requested `response_type`. <br>You must set the `response_type` to be code: `response_type=code`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `server_error`              | The GOV.UK One Login authentication server has experienced an internal server error.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `temporarily_unavailable`   | If you're only making an authentication request (as opposed to requesting both authentication and identity), this error code means the GOV.UK One Login authentication server is temporarily unavailable, which might be caused by temporary overloading or planned maintenance. <br>Make your request again in a few minutes. <br>  <br> If you're making an identity request and you get this error, it means the identity proving and verification does not currently have capacity for this request.                                                                                                                                                                                                                                                                                       |
-| `access_denied`             | GOV.UK One Login returns this error in 3 potential scenarios.<br><br>The first scenario is that the identity evidence your user provided has a lower score than the identity confidence specified in your request. As a result, GOV.UK One Login could not return the medium level of identity confidence (`P2`) and instead returned a lower level of identity confidence.<br><br>The second scenario is that your user selected **Cancel** during the identity verification process.<br><br>The third scenario is that the session in the user’s browser is unavailable. This can happen when your user’s cookies have been lost or your user changed browsers during the identity verification process. In this scenario, you should ask your user to log in again or restart the identity verification process. |
+| `access_denied`             | GOV.UK One Login returns this error in 3 potential scenarios.<br><br>The first scenario is that the identity evidence your user provided has a lower score than the identity confidence specified in your request. As a result, GOV.UK One Login could not return the medium level of identity confidence (`P2`) and instead returned a lower level of identity confidence.<br><br> If you’re using return codes, you will not receive this error. Instead, GOV.UK One Login returns an array of single letter `returnCode` values through the `userinfo` endpoint. Find more information on [understanding the return codes claim](/integrate-with-integration-environment/prove-users-identity/#understand-your-user-s-return-code-claim).<br><br>The second scenario is that your user selected **Cancel** during the identity verification process.<br><br>The third scenario is that the session in the user’s browser is unavailable. This can happen when your user’s cookies have been lost or your user changed browsers during the identity verification process. In this scenario, you should ask your user to log in again or restart the identity verification process. |
 
 ## Make a token request
 

source/integrate-with-integration-environment/prove-users-identity.html.md.erb

@@ -247,6 +247,50 @@ licence, if they submitted one when proving their identity.
 | `issuedBy`       | The organisation that issued the driving licence.                                                                                                                                                                                     |
 | `personalNumber` | The driver number of the driving licence. This is a string unique to the user.                                                                                                                                                        |
 
+## Understand your user’s return code claim
+
+The `https://vocab.account.gov.uk/v1/returnCode` claim gives information about any issues with the evidence your user provided to prove their identity. For example, if GOV.UK One Login was not able to prove your user’s identity. 
+
+To use this claim, you must let us know when [registering your service with GOV.UK One Login][integrate.register-your-service].
+
+When you use this claim and there’s an issue with the evidence your user provided to prove their identity:
+
+1. You’ll receive an authorisation code in the `redirect_uri` instead of an `access_denied` error.
+1. Use this authorisation code to get an ID token and an access token.
+1. When you make a request to the `/userinfo` endpoint using the access token, the response may contain only authentication data, and an array of one or more `returnCode` values, for example `[{"code": "B"},{"code": "C"}]`.
+1. For security reasons, you’ll need to contact GOV.UK One Login on [[email protected]](mailto:[email protected]) for more detailed information on what each return code means.  
+
+You may receive a return code even if a user’s identity verification is successful. Contact GOV.UK One Login on [[email protected]](mailto:[email protected]) for more detailed information on what each return code means.  
+
+| Property         | Definition                                                                                                                                                                                                                            |
+|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `code`     | An array of single letter codes for `returnCode` values. <br><br> You can use these codes to identify the reason(s) for any issues that occurred during the identity proving journey. For security reasons, you’ll need to contact GOV.UK One Login on [[email protected]](mailto:[email protected]) for more detailed information on what each return code means.  
+
+If you want to add this feature to an existing integration, contact GOV.UK One Login on [[email protected]](mailto:[email protected]) to update your client registration. You must also update your code to make sure your integration is able to use the new behaviour. 
+
+
+```
+HTTP/1.1 200 OK
+Content-Type: application/json
+{
+  "sub": "urn:fdc:gov.uk:2022:56P4CMsGh_02YOlWpd8PAOI-2sVlB2nsNU7mcLZYhYw=",
+  "email": "[email protected]",
+  "email_verified": true,
+  "phone_number": "01406946277",
+  "phone_number_verified": true,
+  "updated_at":1311280970,  
+  "https://vocab.account.gov.uk/v1/returnCode": [
+    {
+      "code": "B"
+    },
+    {
+      "code": "C"
+    }
+  ]
+}
+```
+
+
 ## Understand your user's National Insurance number claim
 The <code>https://vocab.account.gov.uk/v1/socialSecurityRecord</code> claim contains the details of your user’s National
 Insurance Number, if they submitted it while proving their identity.