Skip to content

Commit

Permalink
updates return code information and access denied error messaging
Browse files Browse the repository at this point in the history
  • Loading branch information
PippaClarkGDS committed Feb 5, 2025
1 parent 6416456 commit 4d90ae9
Show file tree
Hide file tree
Showing 5 changed files with 13 additions and 7 deletions.
2 changes: 1 addition & 1 deletion source/before-integrating/choose-which-user-attributes-your-service-can-request.html.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ You can find details of the claims in the following table.
| `https://vocab.account.gov.uk/v1/address` | This claim contains your user's postal addresses. |
| `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/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. |
| `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. There's further [guidance on the `returnCode` claim](/integrate-with-integration-environment/prove-users-identity/#understand-your-user-s-return-code-claim). |

You can see more about the structure of this information when you [prove your user’s identity](integrate-with-integration-environment/prove-users-identity).

Expand Down
2 changes: 1 addition & 1 deletion source/before-integrating/register-and-manage-your-service.html.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Whoever registers the service will have the entry tied to their email address. I
| Landing Page URL | It's not possible to configure this yet.<br><br>Send an email to [[email protected]](mailto:[email protected]) if you need to configure this. |
| Sector identifier URI | Specify your service's sector identifier.<br><br>You must not change the sector identifier once your service has started to sign up or migrate users. Doing this will change the subject identifiers GOV.UK One Login creates for each individual user.<br><br>There’s further [guidance on choosing your sector identifier][integrate.choose-sector-id].<br><br>If your service has more than one <code>redirect_uri</code>, you must set the sector identifier in line with the [OpenID Connect Core 1.0 specification][external.oidc-connect-core-pairwise-algorithm]]. |
| Scopes | Enter the scopes your service requires. You must include the <code>openid</code> scope.<br><br>You may choose one or more of the following:<br><br><li><code>email</code><br><br><li><code>phone</code><br><br><br>There’s further [guidance on choosing which user attributes your service can request][integrate.choose-request-scope]. |
| Claims | If you’re requesting identity verification, you must specify which claims your service needs.<br><br>You can choose one or more of the following:<br><br><li><code>https://vocab.account.gov.uk/v1/passport</code><br><br><li><code>https://vocab.account.gov.uk/v1/drivingPermit</code><br><br><li><code>https://vocab.account.gov.uk/v1/coreIdentityJWT</code><br><br><li><code>https://vocab.account.gov.uk/v1/address</code><br><br><li><code>https://vocab.account.gov.uk/v1/returnCode</code><br><br><br><br>There's further guidance on [choosing which claims your service can request][integrate.choose-request-claim]. |
| Claims | If you’re requesting identity verification, you must include <code>https://vocab.account.gov.uk/v1/coreIdentityJWT</code>. We recommend also including <code>https://vocab.account.gov.uk/v1/returnCode</code> to make your error handling more clear. There's further [guidance on return codes](https://docs.sign-in.service.gov.uk/integrate-with-integration-environment/prove-users-identity/#understand-your-user-s-return-code-claim). In addition, you can choose one or more of the following:<br><br><li><code>https://vocab.account.gov.uk/v1/passport</code><br><br><li><code>https://vocab.account.gov.uk/v1/drivingPermit</code><br><br><li><code>https://vocab.account.gov.uk/v1/coreIdentityJWT</code><br><br><li><code>https://vocab.account.gov.uk/v1/address</code><br><br>There's further guidance on [choosing which claims your service can request][integrate.choose-request-claim]. |
| Token Authentication method | Specify the token authentication method your service is using. This will be <code>private_key_jwt</code> or <code>client_secret_post</code>.<br><br>There’s further [guidance on using the correct token authentication method for your service][integrate.use-correct-token-auth-method]. |
| Public key | Only include this if your service is using the <code>private_key_jwt</code> token authentication method.<br><br>Enter the contents of your public key Privacy Enhanced Mail (PEM) file (or whichever file was created when you created your key pair).<br><br>There’s further [guidance on generating a key pair][integrate.generate-key-pair]. |
| ID token signing algorithm | Choose either <code>RS256</code> or <code>ES256</code>.<br><br>By default, GOV.UK One Login will sign the <code>id_token</code> JSON Web Token (JWT) using the <code>ES256</code> algorithm but some third party tooling does not support <code>ES256</code>. If your service needs an alternative algorithm, we can sign your `id_token` JWT using the `RS256` algorithm
Expand Down
1 change: 1 addition & 0 deletions source/integrate-with-integration-environment/authenticate-your-user.html.md.erb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@ After you’ve made a request for authentication and identity, you should then c
"https://vocab.account.gov.uk/v1/address": null,
"https://vocab.account.gov.uk/v1/passport": null,
"https://vocab.account.gov.uk/v1/drivingPermit": null
"https://vocab.account.gov.uk/v1/returnCode": null
}
}
```
Expand Down
13 changes: 9 additions & 4 deletions source/integrate-with-integration-environment/prove-users-identity.html.md.erb
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Prove your user's identity
weight: 5.6
last_reviewed_on: 2024-07-09
last_reviewed_on: 2025-02-12
review_in: 6 months
---

Expand Down Expand Up @@ -326,9 +326,14 @@ licence, if they submitted one when proving their identity.

## 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.
<%= warning_text('We recommend requesting the return code claim to make your error handling more clear. ') %>

To use the `returnCode` claim, you'll need to:

To use this claim, you must let us know when [registering your service with GOV.UK One Login][integrate.register-your-service].
1. Enable the `returnCode` claim when you register your service.
1. Include `https://vocab.account.gov.uk/v1/returnCode` when you [make a request for authentication and identity](https://docs.sign-in.service.gov.uk/integrate-with-integration-environment/authenticate-your-user/#make-a-request-for-authentication-and-identity).

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.

When you use this claim and there’s an issue with the evidence your user provided to prove their identity:

Expand All @@ -337,7 +342,7 @@ When you use this claim and there’s an issue with the evidence your user provi
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, which will each be a letter.
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 issue each `returnCode` value stands for.

Currently, there are 11 `returnCode` values which GOV.UK One Login could return if there’s an issue with the evidence your user provided to prove their identity. You may receive a return code even if a user’s identity verification is successful, for example, if a user is a politically exposed person. Contact GOV.UK One Login on [[email protected]](mailto:[email protected]) for more detailed information on what each return code means.
Currently, there are 9 `returnCode` values which GOV.UK One Login could return if there’s an issue with the evidence your user provided to prove their identity. You may receive a return code even if a user’s identity verification is successful, for example, if a user is a politically exposed person. Contact GOV.UK One Login on [[email protected]](mailto:[email protected]) for more detailed information on what each return code means.

| Property | Definition |
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
Expand Down
Loading

0 comments on commit 4d90ae9

Please sign in to comment.