AP-614 - Update state parameter explanation on authenticate-your-user.html.md.erb

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

@@ -31,7 +31,7 @@ You can find details of the scopes in the following table.
 | `openid`          | Required              | OIDC requests to the `/authorize` endpoint must contain the `openid` scope value to indicate that an application intends to use the OIDC protocol. <br> <br>This will return the sub claim, which uniquely identifies your user. |
 | `email`           | Optional              | Returns the `email` claim, which contains:<ul><li>your user's email address</li><li>`email_verified`, which is a boolean indicating whether your user has verified their email address or not</li></ul> |
 | `phone`           | Optional              | Returns the `phone_number` claim, which contains:<ul><li>your user's phone number</li><li>`phone_number_verified`, which is a boolean indicating whether your user has verified their phone number or not</li></ul> |
-| `wallet-subject-id` | Optional (required to use GOV.UK Wallet) | Returns the `walletSubjectId` claim, which is a pairwise identifier that GOV.UK Wallet uses when it issues a credential. By comparing the returned value with the value GOV.UK Wallet submits when requesting a credential, you can be sure that the user logged into your service and GOV.UK Wallet are the same user. <br> <br>You must include this scope if you plan to [onboard with GOV.UK Wallet](https://docs.wallet.service.gov.uk/before-integrating.html#onboard-with-gov-uk-one-login) after you have onboarded with GOV.UK One Login. <br> <br>The value is returned in the format: <br>`urn:fdc:wallet.account.gov.uk:2024:3c_jJtXcLttICSNrkW7M1vO2_w-SMDm2nrHsZpWQQ9`<br> <br>where the part after `urn:fdc:` is [Base 64 Encoding with URL and Filename Safe Alphabet](https://datatracker.ietf.org/doc/html/rfc4648#section-5) of the output from a SHA256 hash function.    |
+| `wallet-subject-id` | Optional (required to use GOV.UK Wallet) | Returns the `walletSubjectId` claim, which is a pairwise identifier that GOV.UK Wallet uses when it issues a credential. By comparing the returned value with the value GOV.UK Wallet submits when requesting a credential, you can be sure that the user logged into your service and GOV.UK Wallet are the same user. <br> <br>You must include this scope if you plan to [onboard with GOV.UK Wallet](https://docs.wallet.service.gov.uk/issue-credentials/before-integrating.html#onboard-with-gov-uk-one-login after you have onboarded with GOV.UK One Login. <br> <br>The value is returned in the format: <br>`urn:fdc:wallet.account.gov.uk:2024:3c_jJtXcLttICSNrkW7M1vO2_w-SMDm2nrHsZpWQQ9`<br> <br>where the part after `urn:fdc:` is [Base 64 Encoding with URL and Filename Safe Alphabet](https://datatracker.ietf.org/doc/html/rfc4648#section-5) of the output from a SHA256 hash function.    |
 
 ## Choose which claims your service can request
 

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

@@ -182,7 +182,7 @@ Use the guidance in the following table to replace placeholder values in your ex
 | `response_type` | Required             | You must set this value to be code: `response_type=code`.<br><br>If you’re using JAR, make sure the `response_type` values in the query parameters and the request object are identical. |
 | `scope`         | Required             | A space-separated list of scopes. You must include `openid` as one scope value. If you request `openid` but also request other incorrect scopes, the error `invalid_scope` will return with an HTTP 302 instead.<br><br>You should refer to the guidance on [choosing which user attributes your service can request][integrate.choose-user-attributes] for the `scope` parameter.<br><br>If you’re using JAR, make sure the `scope` values in the query parameters and the request object are identical. |
 | `client_id`     | Required             | The [client identifier][integrate.client-id], which we generated for you when you [registered your service to use GOV.UK One Login][integrate.register-your-service] must match your client configuration.<br><br>If you’re using JAR, make sure the `client_id` values in the query parameters and the request object are identical. |
-| `state`         | Required             | When you receive a response at the redirect URL, there must be a way to verify the response came for a request which you sent. The `state` value solves this issue by binding the request and response, which reduces impact of [Cross Site Request Forgery](https://owasp.org/www-community/attacks/csrf) attacks.<br>This value will be returned to the client in the authentication response. |
+| `state`         | Required             | When you receive a response at the redirect URL, there must be a way to verify the response came for a request which you sent. The `state` value solves this issue by binding the request and response, which reduces impact of [Cross Site Request Forgery](https://owasp.org/www-community/attacks/csrf) attacks.<br>This value will be returned to the client in the authentication response. <br> To avoid an `403 The request could not be satisfied` error the parameter should be:<ul><li>small</li><li>opaque and not open to inspection</li><li>a unique value, to avoid hitting the Web Application Firewall (WAF) limit on the `/logout endpoint` and the `/authorize endpoint`</li></ul><br> The WAF limit depends on the length of the whole query string. The limits are:<ul><li>4096 for `/authorize endpoint`</li><li>2048 for `/logout endpoint`</li></ul>|
 | `redirect_uri`  | Required             | You’ll have specified your `redirect_uri` when you [registered your service to use GOV.UK One Login][integrate.register-your-service].<br><br>To avoid an `HTTP 400 Bad Response` error, the redirect URI must exactly match one of the URIs configured in your client configuration and also include the protocol `https://` or `http`.<br><br>If you’re using request parameters, the value must be URL-encoded. |
 | `nonce`         | Required             | A unique value generated by your application that is used to verify the integrity of the `id_token` and mitigate replay attacks.<br>This value will be present in the `id_token` and should include the per-session state, as well as being impossible for attackers to guess.<br>Your application will need to verify the `nonce` claim value is the same as the `nonce` parameter sent in the authentication request. |
 | `response_mode` | Optional | [`response_mode`](https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes) specifies the mechanism used when returning parameters from the `/authorize` endpoint. <br/><br/>You should only provide this parameter if your implementation cannot support `query`, which is the default mode for `response_type=code`.<br/><br/>If your implementation does not support `query`, you can set this parameter using `response_mode=fragment`.|
@@ -555,7 +555,7 @@ If you included a [level of identity confidence][integrate.choose-level-of-confi
 | `email_verified`  | This means the email was verified using a one-time code when the user created their account. This is always `true`. |
 | `phone_number` | This is the phone number your user chose as their current preferred method for receiving two-factor authentication codes. This will only be present when the user's preference is to receive two-factor authentication codes by phone. <br> </br> <br> </br> GOV.UK One Login returns this in the E.164 format with no spaces for both UK and international phone numbers: `+{country-code}Number`.  |
 | `phone_number_verified` | This will be returned as:<br><ul> </li><li>`true` when the user's current preference is set to receive a security code by phone </li><li>`false` when the user's current preference is not set to receive a security code by phone |
-| `walletSubjectId` | This will be returned in the format: <br>`urn:fdc:wallet.account.gov.uk:2024:3c_jJtXcLttICSNrkW7M1vO2_w-SMDm2nrHsZpWQQ9` <br><br>where the part after `urn:fdc:` is [Base 64 Encoding with URL and Filename Safe Alphabet](https://datatracker.ietf.org/doc/html/rfc4648#section-5) of the output from a SHA256 hash function. <br><br>`walletSubjectId` is a pairwise identifier that GOV.UK Wallet uses when it issues a credential. By comparing the returned value with the value GOV.UK Wallet submits when requesting a credential, you can be sure that the user logged into your service and GOV.UK Wallet are the same user. <br><br>You must include this scope if you plan to [onboard with GOV.UK Wallet](https://docs.wallet.service.gov.uk/before-integrating.html#onboard-with-gov-uk-one-login) after you have onboarded with GOV.UK One Login.     |
+| `walletSubjectId` | This will be returned in the format: <br>`urn:fdc:wallet.account.gov.uk:2024:3c_jJtXcLttICSNrkW7M1vO2_w-SMDm2nrHsZpWQQ9` <br><br>where the part after `urn:fdc:` is [Base 64 Encoding with URL and Filename Safe Alphabet](https://datatracker.ietf.org/doc/html/rfc4648#section-5) of the output from a SHA256 hash function. <br><br>`walletSubjectId` is a pairwise identifier that GOV.UK Wallet uses when it issues a credential. By comparing the returned value with the value GOV.UK Wallet submits when requesting a credential, you can be sure that the user logged into your service and GOV.UK Wallet are the same user. <br><br>You must include this scope if you plan to [onboard with GOV.UK Wallet](https://docs.wallet.service.gov.uk/issue-credentials/before-integrating.html#onboard-with-gov-uk-one-login) after you have onboarded with GOV.UK One Login.     |
 
 
 ### Error handling for ‘Retrieve user information’

source/partials/_changelog.erb

@@ -4,19 +4,20 @@
 
 | Publication date | Update                                                                                                                                                                                                                                                                                                                                            |
 |------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Apr 7 2026     | Updates guidance <a href="/integrate-with-integration-environment/authenticate-your-user/#replace-the-placeholder-values-in-your-example">"Authenticate your user"</a> to improve the explanation of the State parameter. |
 | Mar 6 2026       | Updated <a href="/before-integrating/choose-your-sector-identifier/#set-your-sector-identifier">"Set your sector identifier"</a> to emphasise that sector identifiers must be a valid URL using the HTTPS scheme.                                             |
-| Feb 18 2025      | Updates <a href="/integrate-with-integration-environment/authenticate-your-user/#make-a-token-request"> guidance to add details that audience claim can be either token URI or issuer URI</a>.                                             |
+| Feb 18 2026      | Updates <a href="/integrate-with-integration-environment/authenticate-your-user/#make-a-token-request"> guidance to add details that audience claim can be either token URI or issuer URI</a>.                                             |
 | Feb 17 2026      | Updates guidance <a href="/before-integrating/set-up-your-public-and-private-keys/#share-your-public-keys-with-gov-uk-one-login">"Share your public keys using a JWKS endpoint"</a> to clarify how to use a JWKS endpoint. | 
 | Feb 16 2026      | Updates website header to clarify this website is the technical documentation for GOV.UK One Login.| 
 | Jan 19 2026      | Added new diagram <a href="how-gov-uk-one-login-works/#gov-uk-one-login-oidc-authorization-code-flow">"GOV.UK One Login OIDC Flow"</a> in UML format which describes the authorisation flow in more detail.|
 | Nov 10 2025      | Updates guidance <a href="/integrate-with-integration-environment/authenticate-your-user/#use-the-integration-discovery-endpoint">"Use the integration discovery endpoint"</a> to add information about caching.|
-| Nov 5 2024       | Updates guidance <a href="/integrate-with-integration-environment/authenticate-your-user/#replace-the-placeholder-values-in-your-example">"Replace the placeholder values in your example"</a> to explain the use of the `response_mode` parameter passed to the `/authorize` endpoint.
-| Oct 28 2024      | Updates guidance <a href="/integrate-with-integration-environment/authenticate-your-user/#validate-your-id-token">"Validate your ID token"</a> to explain the frequency of key rotations for the environments.
+| Nov 5 2025       | Updates guidance <a href="/integrate-with-integration-environment/authenticate-your-user/#replace-the-placeholder-values-in-your-example">"Replace the placeholder values in your example"</a> to explain the use of the `response_mode` parameter passed to the `/authorize` endpoint.
+| Oct 28 2025      | Updates guidance <a href="/integrate-with-integration-environment/authenticate-your-user/#validate-your-id-token">"Validate your ID token"</a> to explain the frequency of key rotations for the environments.
 | Oct 23 2025      | Added guidance <a href="/before-integrating/set-user-agent-header">"Setting a User-Agent header on HTTP requests"</a> the requirement to use an appropriate `User-Agent` header on service calls to GOV.UK One Login. |
 | Sep 2 2025       | Updates guidance <a href="/integrate-with-integration-environment/prove-users-identity/#prove-your-user-39-s-identity">"Prove your user's identity"</a> with guidance for helping your users after their in-person identity checks.     |
 | Jul 30 2025      | Updates guidance <a href="/before-integrating/choose-which-user-attributes-your-service-can-request/#choose-which-scopes-your-service-can-request">"Choose which scopes your service can request"</a> and <a href="/integrate-with-integration-environment/authenticate-your-user/#receive-response-for-retrieve-user-information">"Retrieve user information"</a> to add information about the `wallet-subject-id` scope.     |
 | Jun 12 2025      | Updates section on testing to remove guidance on building mocks and move guidance on <a href="/test-your-integration/gov-uk-one-login-simulator/">"using the GOV.UK One Login simulator"</a> to section on <a href="/test-your-integration/">"testing your integration with GOV.UK One Login"</a>.                                                |
-| May 2 2024       | Updates <a href="/integrate-with-integration-environment/authenticate-your-user/#make-a-request-to-the-authorize-endpoint"> guidance to add information about using Proof Key for Code Exchange (PKCE) parameters in the authorise request.</a> Updates guidance <a href="/integrate-with-integration-environment/authenticate-your-user/#make-a-token-request"> to include information about using PKCE parameters in the token request.</a> Updates guidance <a href="/configure-for-production/"> to include guidance about `PKCEEnforced` field when configuring your service</a>.                                             |
+| May 2 2025       | Updates <a href="/integrate-with-integration-environment/authenticate-your-user/#make-a-request-to-the-authorize-endpoint"> guidance to add information about using Proof Key for Code Exchange (PKCE) parameters in the authorise request.</a> Updates guidance <a href="/integrate-with-integration-environment/authenticate-your-user/#make-a-token-request"> to include information about using PKCE parameters in the token request.</a> Updates guidance <a href="/configure-for-production/"> to include guidance about `PKCEEnforced` field when configuring your service</a>.                                             |
 | Apr 15 2025      | Updates guidance <a href="/integrate-with-integration-environment/managing-your-users-sessions/#managing-user-sessions-if-your-service-session-is-less-than-1-hour">"Managing user sessions if your service session is less than 1 hour"</a> to add guidance on how to re-authenticate your users.  Updates the <a href="/integrate-with-integration-environment/authenticate-your-user/#error-handling-for-make-a-request-to-the-authorize-endpoint">'Make a request to the /authorize endpoint' table</a> to add an entry for `login_required` error code. |                                                              |
 | Apr 2 2025       | New guidance <a href="/test-your-integration/gov-uk-one-login-simulator/">"Test your service with the GOV.UK One Login simulator"</a> to add information about the new GOV.UK One Login simulator.                                                                                                                                                                      |
 | Mar 5 2025       | Updates guidance <a href="/before-integrating/integrating-third-party-platform/#integrating-third-party-platforms-with-gov-uk-one-login">"Integrating third-party platforms with GOV.UK One Login"</a> to add guidance on integrating with GOV.UK One Login using Amazon Cognito.                                                                |