Make claims-based caching configurable (#6163)

This PR: - Sets ability to cache based on requested claims as a configurable option under `CacheOptions.claimsBasedCachinEnabled` - Changes default behavior so in v3 claims-based caching is off by default and any request containing claims will go to the network - Provides a mitigation to the issue where requesting different claims results in a cache miss and a cached token accumulation with no practical way to clear unused tokens - Backport for LTS packages (msal-node v1/msal-browser v2) in progress
AzureAD · Jul 5, 2023 · 4ccef1b · 4ccef1b
1 parent faae9de
commit 4ccef1b
Show file tree

Hide file tree

Showing 26 changed files with 895 additions and 210 deletions.
diff --git a/change/@azure-msal-browser-b9572127-f4c0-473a-a120-61bb7d2850c6.json b/change/@azure-msal-browser-b9572127-f4c0-473a-a120-61bb7d2850c6.json
@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Make claims-based caching configurable #6163",
+  "packageName": "@azure/msal-browser",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}
diff --git a/change/@azure-msal-common-b6ff22a1-1e2b-4000-ab22-1f1eec784b62.json b/change/@azure-msal-common-b6ff22a1-1e2b-4000-ab22-1f1eec784b62.json
@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Make claims-based caching configurable #6163",
+  "packageName": "@azure/msal-common",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}
diff --git a/change/@azure-msal-node-44b62ae5-8011-430c-aca4-e7230b9845e9.json b/change/@azure-msal-node-44b62ae5-8011-430c-aca4-e7230b9845e9.json
@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Make claims-based caching configurable #6163",
+  "packageName": "@azure/msal-node",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}
diff --git a/lib/msal-browser/docs/configuration.md b/lib/msal-browser/docs/configuration.md
diff --git a/lib/msal-browser/docs/v2-migration.md b/lib/msal-browser/docs/v2-migration.md
@@ -59,6 +59,25 @@ const msalConfig = {
 const msalInstance = await msal.PublicClientApplication.createPublicClientApplication(msalConfig);
 ```
 
+### Claims-based caching
+
+In MSAL v2.x, adding claims to a request will result in a hash of the requested claims string being added to the token cache key by default. This implies that MSAL 2.x caches and matches tokens based on claims by default. In MSAL v3.x, this behavior is no longer the default. MSAL v3.x default behavior is to go to the network to refresh a token every time claims are requested, regardless of whether the token has been cached previously and is still valid. Then, after going to the network, the token received overwrites the cached token in case a silent request without claims is executed later. In order to enable claims-based caching in MSAL v3.x to maintain the same behavior as in MSAL v2.x, developers must use the `cacheOptions.claimsBasedCachingEnabled` configuration flag set to true in the Client Application configuration object:
+
+```typescript
+const msalConfig = {
+    auth: {
+        ...
+    },
+    ...
+    cache: {
+        claimsBasedCachingEnabled: true
+    }
+}
+
+const msalInstance = new msal.PublicClientApplication(msalConfig);
+await msalInstance.initialize();
+```
+
 All other APIs are backward compatible with [MSAL v2.x](../../msal-browser/). It is recommended to take a look at the [default sample](../../../samples/msal-browser-samples/VanillaJSTestApp2.0) to see a working example of MSAL v3.0.
 
 ### Crypto

diff --git a/lib/msal-browser/src/cache/BrowserCacheManager.ts b/lib/msal-browser/src/cache/BrowserCacheManager.ts
@@ -1891,6 +1891,7 @@ export const DEFAULT_BROWSER_CACHE_MANAGER = (
         storeAuthStateInCookie: false,
         secureCookies: false,
         cacheMigrationEnabled: false,
+        claimsBasedCachingEnabled: false,
     };
     return new BrowserCacheManager(
         clientId,

diff --git a/lib/msal-browser/src/config/Configuration.ts b/lib/msal-browser/src/config/Configuration.ts
@@ -108,6 +108,10 @@ export type CacheOptions = {
      * 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.
      */
     cacheMigrationEnabled?: boolean;
+    /**
+     * Flag that determines whether access tokens are stored based on requested claims
+     */
+    claimsBasedCachingEnabled?: boolean;
 };
 
 export type BrowserSystemOptions = SystemOptions & {
@@ -255,6 +259,7 @@ export function buildConfiguration(
             userInputCache.cacheLocation === BrowserCacheLocation.LocalStorage
                 ? true
                 : false,
+        claimsBasedCachingEnabled: false,
     };
 
     // Default logger options for browser
@@ -290,7 +295,7 @@ export function buildConfiguration(
         nativeBrokerHandshakeTimeout:
             userInputSystem?.nativeBrokerHandshakeTimeout ||
             DEFAULT_NATIVE_BROKER_HANDSHAKE_TIMEOUT_MS,
-        pollIntervalMilliseconds: BrowserConstants.DEFAULT_POLL_INTERVAL_MS
+        pollIntervalMilliseconds: BrowserConstants.DEFAULT_POLL_INTERVAL_MS,
     };
 
     const providedSystemOptions: BrowserSystemOptions = {

diff --git a/lib/msal-browser/src/controllers/StandardController.ts b/lib/msal-browser/src/controllers/StandardController.ts
@@ -198,10 +198,7 @@ export class StandardController implements IController {
 
         // Initialize the crypto class.
         this.browserCrypto = this.isBrowserEnvironment
-            ? new CryptoOps(
-                  this.logger,
-                  this.performanceClient
-              )
+            ? new CryptoOps(this.logger, this.performanceClient)
             : DEFAULT_CRYPTO_IMPLEMENTATION;
 
         this.eventHandler = new EventHandler(this.logger, this.browserCrypto);
@@ -226,6 +223,7 @@ export class StandardController implements IController {
             storeAuthStateInCookie: false,
             secureCookies: false,
             cacheMigrationEnabled: false,
+            claimsBasedCachingEnabled: false,
         };
         this.nativeInternalStorage = new BrowserCacheManager(
             this.config.auth.clientId,

diff --git a/lib/msal-browser/src/interaction_client/BaseInteractionClient.ts b/lib/msal-browser/src/interaction_client/BaseInteractionClient.ts
@@ -178,8 +178,13 @@ export abstract class BaseInteractionClient {
             );
         }
 
-        // Set requested claims hash if claims were requested
-        if (request.claims && !StringUtils.isEmpty(request.claims)) {
+        // Set requested claims hash if claims-based caching is enabled and claims were requested
+        if (
+            this.config.cache.claimsBasedCachingEnabled &&
+            request.claims &&
+            // Checks for empty stringified object "{}" which doesn't qualify as requested claims
+            !StringUtils.isEmptyObj(request.claims)
+        ) {
             validatedRequest.requestedClaimsHash =
                 await this.browserCrypto.hashString(request.claims);
         }
@@ -210,10 +215,15 @@ export abstract class BaseInteractionClient {
      * If authority provided in the request does not match environment/authority specified
      * in the account or MSAL config, we throw an error.
      */
-    async validateRequestAuthority(authority: string, account: AccountInfo): Promise<void> {
-        const discoveredAuthority = await this.getDiscoveredAuthority(authority);
+    async validateRequestAuthority(
+        authority: string,
+        account: AccountInfo
+    ): Promise<void> {
+        const discoveredAuthority = await this.getDiscoveredAuthority(
+            authority
+        );
 
-        if(!discoveredAuthority.isAlias(account.environment)) {
+        if (!discoveredAuthority.isAlias(account.environment)) {
             throw ClientConfigurationError.createAuthorityMismatchError();
         }
     }

diff --git a/lib/msal-browser/src/interaction_client/StandardInteractionClient.ts b/lib/msal-browser/src/interaction_client/StandardInteractionClient.ts
@@ -278,6 +278,10 @@ export abstract class StandardInteractionClient extends BaseInteractionClient {
                 logLevel: logger.logLevel,
                 correlationId: this.correlationId,
             },
+            cacheOptions: {
+                claimsBasedCachingEnabled:
+                    this.config.cache.claimsBasedCachingEnabled,
+            },
             cryptoInterface: this.browserCrypto,
             networkInterface: this.networkClient,
             storageInterface: this.browserStorage,