Add security guidance for state parameter usage in authentication flows

change/@azure-msal-browser-32e0b932-d6ae-4583-8e28-460258c5a6ca.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "docs: Add security guidance for state parameter usage",
+  "packageName": "@azure/msal-browser",
+  "email": "198982749+Copilot@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

change/@azure-msal-common-586c8ff0-7f47-4514-b4bb-0b639b5efe59.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "docs: Add security guidance for state parameter usage",
+  "packageName": "@azure/msal-common",
+  "email": "198982749+Copilot@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

lib/msal-browser/src/request/PopupRequest.ts

@@ -15,7 +15,7 @@ import { PopupWindowAttributes } from "./PopupWindowAttributes.js";
  * - correlationId              - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
  * - redirectUri                - The redirect URI where authentication responses can be received by your application. It must exactly match one of the redirect URIs registered in the Azure portal.
  * - extraScopesToConsent       - Scopes for a different resource when the user needs consent upfront.
- * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred.
+ * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred. For security and privacy reasons, we do not recommend putting URLs or other sensitive data directly in the state parameter. Instead, use a key or identifier that corresponds to data stored in browser storage (e.g., localStorage, sessionStorage), allowing your app to securely reference the necessary data after authentication.
  * - prompt                     - Indicates the type of user interaction that is required.
  *          login: will force the user to enter their credentials on that request, negating single-sign on
  *          none:  will ensure that the user isn't presented with any interactive prompt. if request can't be completed via single-sign on, the endpoint will return an interaction_required error

lib/msal-browser/src/request/RedirectRequest.ts

@@ -14,7 +14,7 @@ import { CommonAuthorizationUrlRequest } from "@azure/msal-common/browser";
  * - correlationId              - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
  * - redirectUri                - The redirect URI where authentication responses can be received by your application. It must exactly match one of the redirect URIs registered in the Azure portal.
  * - extraScopesToConsent       - Scopes for a different resource when the user needs consent upfront.
- * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred.
+ * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred. For security and privacy reasons, we do not recommend putting URLs or other sensitive data directly in the state parameter. Instead, use a key or identifier that corresponds to data stored in browser storage (e.g., localStorage, sessionStorage), allowing your app to securely reference the necessary data after authentication.
  * - prompt                     - Indicates the type of user interaction that is required.
  *          login: will force the user to enter their credentials on that request, negating single-sign on
  *          none:  will ensure that the user isn't presented with any interactive prompt. if request can't be completed via single-sign on, the endpoint will return an interaction_required error

lib/msal-browser/src/request/SsoSilentRequest.ts

@@ -14,7 +14,7 @@ import { CommonAuthorizationUrlRequest } from "@azure/msal-common/browser";
  * - correlationId              - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
  * - redirectUri                - The redirect URI where authentication responses can be received by your application. It must exactly match one of the redirect URIs registered in the Azure portal.
  * - extraScopesToConsent       - Scopes for a different resource when the user needs consent upfront.
- * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred.
+ * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred. For security and privacy reasons, we do not recommend putting URLs or other sensitive data directly in the state parameter. Instead, use a key or identifier that corresponds to data stored in browser storage (e.g., localStorage, sessionStorage), allowing your app to securely reference the necessary data after authentication.
  * - prompt                     - Indicates the type of user interaction that is required.
  *          login: will force the user to enter their credentials on that request, negating single-sign on
  *          none:  will ensure that the user isn't presented with any interactive prompt. if request can't be completed via single-sign on, the endpoint will return an interaction_required error

lib/msal-common/src/request/CommonAuthorizationUrlRequest.ts

@@ -19,7 +19,7 @@ import { AccountInfo } from "../account/AccountInfo.js";
  * - responseMode               - Specifies the method that should be used to send the authentication result to your app. Can be query, form_post, or fragment. If no value is passed in, it defaults to query.
  * - codeChallenge              - Used to secure authorization code grant via Proof of Key for Code Exchange (PKCE). For more information, see the PKCE RCF:https://tools.ietf.org/html/rfc7636
  * - codeChallengeMethod        - The method used to encode the code verifier for the code challenge parameter. Can be "plain" or "S256". If excluded, code challenge is assumed to be plaintext. For more information, see the PKCE RCF: https://tools.ietf.org/html/rfc7636
- * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred.
+ * - state                      - A value included in the request that is also returned in the token response. A randomly generated unique value is typically used for preventing cross site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred. For security and privacy reasons, we do not recommend putting URLs or other sensitive data directly in the state parameter. Instead, use a key or identifier that corresponds to data stored in browser storage (e.g., localStorage, sessionStorage), allowing your app to securely reference the necessary data after authentication.
  * - prompt                     - Indicates the type of user interaction that is required.
  *          login: will force the user to enter their credentials on that request, negating single-sign on
  *          none:  will ensure that the user isn't presented with any interactive prompt. if request can't be completed via single-sign on, the endpoint will return an interaction_required error

lib/msal-common/src/request/CommonEndSessionRequest.ts

@@ -12,7 +12,7 @@ import { StringDict } from "../utils/MsalTypes.js";
  * - postLogoutRedirectUri  - URI to navigate to after logout page.
  * - correlationId          - Unique GUID set per request to trace a request end-to-end for telemetry purposes.
  * - idTokenHint            - ID Token used by B2C to validate logout if required by the policy
- * - state                  - A value included in the request to the logout endpoint which will be returned in the query string upon post logout redirection
+ * - state                  - A value included in the request to the logout endpoint which will be returned in the query string upon post logout redirection. For security and privacy reasons, we do not recommend putting URLs or other sensitive data directly in the state parameter. Instead, use a key or identifier that corresponds to data stored in browser storage (e.g., localStorage, sessionStorage), allowing your app to securely reference the necessary data after logout.
  * - logoutHint             - A string that specifies the account that is being logged out in order to skip the server account picker on logout
  * - extraQueryParameters   - String to string map of custom query parameters added to the /authorize call
  */