[v5] Changes to Configuration - CacheOptions (Config #2) (#7697)

This PR updates the CacheOptions for MSAL Browser v5, including the
removal of implementation, tests, and doc references for the following
options:
- `temporaryCacheLocation`
- `claimsBasedCachingEnabled`
- `storeAuthStateInCookie`
- `secureCookies`
- `cacheMigrationEnabled`

Deprecation notices for the above options were added in #7707

---------

Co-authored-by: Thomas Norling <[email protected]>

Author: jo-arroyo

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -109,7 +109,6 @@ body:
                 },
                 cache: {
                   cacheLocation: "sessionStorage"
-                  storeAuthStateInCookie: false
                 }
               }
       validations:

change/@azure-msal-browser-6f00d163-ea6e-4461-8d64-f654afaa2e5c.json

@@ -0,0 +1,7 @@
+{
+  "type": "major",
+  "comment": "Configuration changes to CacheOptions #7697",
+  "packageName": "@azure/msal-browser",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-common-c037e1e0-4f7a-49c5-912a-ce0ea99fcf1e.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Deprecate claimsBasedCachingEnabled as part of Configuration change #7697",
+  "packageName": "@azure/msal-common",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

docs/errors.md

@@ -17,8 +17,7 @@ This error occurs when MSAL.js surpasses the allotted storage limit when attempt
 
 **Mitigation**:
 
-1. Make sure the configured cache storage has enough capacity to allow MSAL.js to persist token payload. The amount of cache storage required depends on the number of [cached artifacts](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser/docs/caching.md#cached-artifacts).
-2. Disable [claimsBasedCachingEnabled](https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-browser/docs/configuration.md#cache-config-options) cache config option. When enabled, it caches access tokens under a key containing the hash of the requested claims. Depending on the MSAL.js API usage, it may result in the vast number of access tokens persisted in the cache storage.
+1. Make sure the configured cache storage has enough capacity to allow MSAL.js to persist token payload. The amount of cache storage required depends on the number of [cached artifacts](./caching.md#cached-artifacts).
 
 ### `cache_error_unknown`
 - An unknown error occurred while accessing the browser cache.

lib/msal-angular/docs/configuration.md

@@ -58,7 +58,6 @@ import { PublicClientApplication, InteractionType, BrowserCacheLocation } from "
         },
         cache: {
           cacheLocation: BrowserCacheLocation.LocalStorage,
-          storeAuthStateInCookie: true, // Deprecated, will be removed in the next major version
         },
         system: {
           loggerOptions: {
@@ -261,7 +260,6 @@ fetch("/assets/configuration.json")
     },
     "cache": {
       "cacheLocation": "localStorage",
-      "storeAuthStateInCookie": true
     }
   },
   "guard": {
@@ -471,7 +469,6 @@ export class AppModule {}
     },
     "cache": {
       "cacheLocation": "localStorage",
-      "storeAuthStateInCookie": true
     }
   },
   "guard": {

lib/msal-angular/docs/events.md

@@ -222,7 +222,6 @@ import { PublicClientApplication, InteractionType, BrowserCacheLocation } from "
             },
             cache: {
                 cacheLocation : BrowserCacheLocation.LocalStorage,
-                storeAuthStateInCookie: true, // set to true for IE 11
             },
             system: {
                 loggerOptions: {

lib/msal-angular/docs/initialization.md

@@ -31,7 +31,6 @@ import { PublicClientApplication, InteractionType, BrowserCacheLocation } from "
             },
             cache: {
                 cacheLocation : BrowserCacheLocation.LocalStorage,
-                storeAuthStateInCookie: true, // Deprecated, will be removed in future version
             },
             system: {
                 loggerOptions: {
@@ -115,7 +114,6 @@ import { PublicClientApplication, InteractionType, BrowserCacheLocation } from "
             },
             cache: {
                 cacheLocation : BrowserCacheLocation.LocalStorage,
-                storeAuthStateInCookie: true, // Deprecated, will be removed in future version
             },
             system: {
                 loggerOptions: {

lib/msal-browser/apiReview/msal-browser.api.md

@@ -403,10 +403,6 @@ export type CacheLookupPolicy = (typeof CacheLookupPolicy)[keyof typeof CacheLoo
 // @public
 export type CacheOptions = {
     cacheLocation?: BrowserCacheLocation | string;
-    temporaryCacheLocation?: BrowserCacheLocation | string;
-    storeAuthStateInCookie?: boolean;
-    cacheMigrationEnabled?: boolean;
-    claimsBasedCachingEnabled?: boolean;
 };
 
 // Warning: (ae-missing-release-tag) "ClearCacheRequest" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -1491,7 +1487,7 @@ export type WrapperSKU = (typeof WrapperSKU)[keyof typeof WrapperSKU];
 // src/cache/LocalStorage.ts:296:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/cache/LocalStorage.ts:354:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/cache/LocalStorage.ts:385:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
-// src/config/Configuration.ts:231:5 - (ae-forgotten-export) The symbol "InternalAuthOptions" needs to be exported by the entry point index.d.ts
+// src/config/Configuration.ts:211:5 - (ae-forgotten-export) The symbol "InternalAuthOptions" needs to be exported by the entry point index.d.ts
 // src/event/EventHandler.ts:113:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/event/EventHandler.ts:139:8 - (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
 // src/index.ts:8:12 - (tsdoc-characters-after-block-tag) The token "@azure" looks like a TSDoc tag but contains an invalid character "/"; if it is not a tag, use a backslash to escape the "@"

lib/msal-browser/docs/caching.md

@@ -66,20 +66,10 @@ To faciliate efficient token acquisition while maintaining a good UX, MSAL cache
     - previous failed request 
     - performance data
 
-> :bulb: Temporary cache entries will always be stored in session storage or in memory unless overridden by the user with the `temporaryCacheLocation` cache option. MSAL will fallback to memory storage if local/session storage is not available. Please read the warning below for more information.
+> :bulb: Temporary cache entries will always be stored in session storage or in memory. MSAL will fallback to memory storage if sessionStorage is not available.
 
 > :bulb: The authorization code is only stored in memory and will be discarded after redeeming it for tokens.
 
-## Warning :warning:
-
-**NOTE: `temporaryCacheLocation` is deprecated will be removed in the next major version.**
-
-Overriding `temporaryCacheLocation` should be done with caution. Specifically when choosing `localStorage`. Interaction in more than one tab/window will not be supported and you may receive `interaction_in_progress` errors unexpectedly. This is an escape hatch, not a fully supported feature.
-
-When using MSAL.js with the default configuration in a scenario where the user is redirected after successful authentication in a new window or tab, the OAuth 2.0 Authorization Code with PKCE flow will be interrupted. In this case, the original window or tab where the authentication state (code verifier and challenge) are stored, will be lost, and the authentication flow will fail.
-
-To handle this scenario, you can configure MSAL to use `localStorage` as the cache location by overriding the `temporaryCacheLocation` configuration property. This allows the code verifier and challenge to be stored in the browser's `localStorage,` which is persistent across multiple tabs and windows.
-
 ## Remarks
 
 - We do not recommend apps having business logic dependent on direct use of entities in the cache. Instead, use the appropriate MSAL API when you need to acquire tokens or retrieve accounts.

lib/msal-browser/docs/configuration.md

@@ -22,10 +22,6 @@ const msalConfig = {
     },
     cache: {
         cacheLocation: "sessionStorage",
-        temporaryCacheLocation: "sessionStorage",
-        storeAuthStateInCookie: false,
-        secureCookies: false,
-        claimsBasedCachingEnabled: true,
     },
     system: {
         loggerOptions: {
@@ -96,16 +92,6 @@ const msalInstance = new PublicClientApplication(msalConfig);
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
 | `cacheLocation`             | Location of token cache in browser.                                                                                                                                                                                                                                                                                                                                                                                             | String value that must be one of the following: `"sessionStorage"`, `"localStorage"`, `"memoryStorage"` | `sessionStorage`                                    |
 
-**Note: The following cache config options are deprecated and will be removed in the next major version**
-
-| Option                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                     | Format                                                                                                  | Default Value                                       |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
-| `temporaryCacheLocation`    | Location of temporary cache in browser. This option should only be changed for specific edge cases. Please refer to [caching](https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-browser/docs/caching.md#cached-artifacts) for more.                                                                                                                                                          | String value that must be one of the following: `"sessionStorage"`, `"localStorage"`, `"memoryStorage"` | `sessionStorage`                                    |
-| `storeAuthStateInCookie`    | If true, stores cache items in cookies as well as browser cache. Should be set to true for use cases using IE.                                                                                                                                                                                                                                                                                                                  | boolean                                                                                                 | `false`                                             |
-| `secureCookies`             | If true and `storeAuthStateInCookies` is also enabled, MSAL adds the `Secure` flag to the browser cookie so it can only be sent over HTTPS.                                                                                                                                                                                                                                                                                     | boolean                                                                                                 | `false`                                             |
-| `cacheMigrationEnabled`     | If true, cache entries from older versions of MSAL will be updated to conform to the latest cache schema on startup. If your application has not been recently updated to a new version of MSAL.js you can safely turn this off. In the event old cache entries are not migrated it may result in a cache miss when attempting to retrieve accounts or tokens and affected users may need to re-authenticate to get up to date. | boolean                                                                                                 | `true` when using `localStorage`, `false` otherwise |
-| `claimsBasedCachingEnabled` | If `true`, access tokens will be cached under a key containing the hash of the requested claims string, resulting in a cache miss and new network token request when the same token request is made with different or missing claims. If set to `false`, tokens will be cached without claims, but all requests containing claims will go to the network and overwrite any previously cached token with the same scopes.        | boolean                                                                                                 | `false`                                             |
-
 See [Caching in MSAL](./caching.md) for more.
 
 ### System Config Options

lib/msal-browser/src/cache/BrowserCacheManager.ts

@@ -70,8 +70,6 @@ import { clearHash } from "../utils/BrowserUtils.js";
 
 /**
  * This class implements the cache storage interface for MSAL through browser local or session storage.
- * Cookies are only used if storeAuthStateInCookie is true, and are only used for
- * parameters such as state and nonce, generally.
  */
 export class BrowserCacheManager extends CacheManager {
     // Cache configuration, either set by user or default values.
@@ -112,7 +110,7 @@ export class BrowserCacheManager extends CacheManager {
         );
         this.temporaryCacheStorage = getStorageImplementation(
             clientId,
-            cacheConfig.temporaryCacheLocation,
+            BrowserCacheLocation.SessionStorage,
             logger,
             performanceClient
         );
@@ -890,21 +888,10 @@ export class BrowserCacheManager extends CacheManager {
 
     /**
      * Gets cache item with given key.
-     * Will retrieve from cookies if storeAuthStateInCookie is set to true.
      * @param key
      */
     getTemporaryCache(cacheKey: string, generateKey?: boolean): string | null {
         const key = generateKey ? this.generateCacheKey(cacheKey) : cacheKey;
-        if (this.cacheConfig.storeAuthStateInCookie) {
-            const itemCookie = this.cookieStorage.getItem(key);
-            if (itemCookie) {
-                this.logger.trace(
-                    "BrowserCacheManager.getTemporaryCache: storeAuthStateInCookies set to true, retrieving from cookies"
-                );
-                return itemCookie;
-            }
-        }
-
         const value = this.temporaryCacheStorage.getItem(key);
         if (!value) {
             // If temp cache item not found in session/memory, check local storage for items set by old versions
@@ -933,8 +920,6 @@ export class BrowserCacheManager extends CacheManager {
 
     /**
      * Sets the cache item with the key and value given.
-     * Stores in cookie if storeAuthStateInCookie is set to true.
-     * This can cause cookie overflow if used incorrectly.
      * @param key
      * @param value
      */
@@ -944,14 +929,7 @@ export class BrowserCacheManager extends CacheManager {
         generateKey?: boolean
     ): void {
         const key = generateKey ? this.generateCacheKey(cacheKey) : cacheKey;
-
         this.temporaryCacheStorage.setItem(key, value);
-        if (this.cacheConfig.storeAuthStateInCookie) {
-            this.logger.trace(
-                "BrowserCacheManager.setTemporaryCache: storeAuthStateInCookie set to true, setting item cookie"
-            );
-            this.cookieStorage.setItem(key, value, undefined);
-        }
     }
 
     /**
@@ -964,17 +942,10 @@ export class BrowserCacheManager extends CacheManager {
 
     /**
      * Removes the temporary cache item with the given key.
-     * Will also clear the cookie item if storeAuthStateInCookie is set to true.
      * @param key
      */
     removeTemporaryItem(key: string): void {
         this.temporaryCacheStorage.removeItem(key);
-        if (this.cacheConfig.storeAuthStateInCookie) {
-            this.logger.trace(
-                "BrowserCacheManager.removeItem: storeAuthStateInCookie is true, clearing item cookie"
-            );
-            this.cookieStorage.removeItem(key);
-        }
     }
 
     /**
@@ -1385,10 +1356,6 @@ export const DEFAULT_BROWSER_CACHE_MANAGER = (
 ): BrowserCacheManager => {
     const cacheOptions: Required<CacheOptions> = {
         cacheLocation: BrowserCacheLocation.MemoryStorage,
-        temporaryCacheLocation: BrowserCacheLocation.MemoryStorage,
-        storeAuthStateInCookie: false,
-        cacheMigrationEnabled: false,
-        claimsBasedCachingEnabled: false,
     };
     return new BrowserCacheManager(
         clientId,

lib/msal-browser/src/config/Configuration.ts

@@ -113,26 +113,6 @@ export type CacheOptions = {
      * Used to specify the cacheLocation user wants to set. Valid values are "localStorage", "sessionStorage" and "memoryStorage".
      */
     cacheLocation?: BrowserCacheLocation | string;
-    /**
-     * Used to specify the temporaryCacheLocation user wants to set. Valid values are "localStorage", "sessionStorage" and "memoryStorage".
-     * @deprecated This option is deprecated and will be removed in the next major version.
-     */
-    temporaryCacheLocation?: BrowserCacheLocation | string;
-    /**
-     * If set, MSAL stores the auth request state required for validation of the auth flows in the browser cookies. By default this flag is set to false.
-     * @deprecated This option is deprecated and will be removed in the next major version.
-     */
-    storeAuthStateInCookie?: boolean;
-    /**
-     * If set, MSAL will attempt to migrate cache entries from older versions on initialization. By default this flag is set to true if cacheLocation is localStorage, otherwise false.
-     * @deprecated This option is deprecated and will be removed in the next major version.
-     */
-    cacheMigrationEnabled?: boolean;
-    /**
-     * Flag that determines whether access tokens are stored based on requested claims
-     * @deprecated This option is deprecated and will be removed in the next major version.
-     */
-    claimsBasedCachingEnabled?: boolean;
 };
 
 export type BrowserSystemOptions = SystemOptions & {
@@ -282,15 +262,6 @@ export function buildConfiguration(
     // Default cache options for browser
     const DEFAULT_CACHE_OPTIONS: Required<CacheOptions> = {
         cacheLocation: BrowserCacheLocation.SessionStorage,
-        temporaryCacheLocation: BrowserCacheLocation.SessionStorage,
-        storeAuthStateInCookie: false,
-        // Default cache migration to true if cache location is localStorage since entries are preserved across tabs/windows. Migration has little to no benefit in sessionStorage and memoryStorage
-        cacheMigrationEnabled:
-            userInputCache &&
-            userInputCache.cacheLocation === BrowserCacheLocation.LocalStorage
-                ? true
-                : false,
-        claimsBasedCachingEnabled: false,
     };
 
     // Default logger options for browser