Extend proactive token refresh to client_credentials

change/@azure-msal-common-b0f24abd-2c63-4840-990b-29ee443b640a.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Extend proactive token refresh to client_credentials #6102",
+  "packageName": "@azure/msal-common",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

change/@azure-msal-node-9b01df06-64f9-4f34-8a6b-0bb05ab12f14.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "Extend proactive token refresh to client_credentials #6102",
+  "packageName": "@azure/msal-node",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}

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

@@ -93,7 +93,7 @@ export class RequestValidator {
         }
 
         // Remove any query parameters already included in SSO params
-        queryParams.forEach((value, key) => {
+        queryParams.forEach((_value, key) => {
             if (eQParams[key]) {
                 delete eQParams[key];
             }

lib/msal-common/src/response/AuthenticationResult.ts

@@ -17,6 +17,7 @@ import { AccountInfo } from "../account/AccountInfo";
  * - fromCache              - Boolean denoting whether token came from cache
  * - expiresOn              - Javascript Date object representing relative expiration of access token
  * - extExpiresOn           - Javascript Date object representing extended relative expiration of access token in case of server outage
+ * - refreshOn              - Javascript Date object representing relative time until an access token must be refreshed
  * - state                  - Value passed in by user in request
  * - familyId               - Family ID identifier, usually only used for refresh tokens
  * - requestId              - Request ID returned as part of the response
@@ -32,10 +33,11 @@ export type AuthenticationResult = {
     accessToken: string;
     fromCache: boolean;
     expiresOn: Date | null;
+    extExpiresOn?: Date;
+    refreshOn: Date | null;
     tokenType: string;
     correlationId: string;
     requestId?: string;
-    extExpiresOn?: Date;
     state?: string;
     familyId?: string;
     cloudGraphHostName?: string;

lib/msal-common/src/response/ResponseHandler.ts

@@ -28,6 +28,7 @@ import {
     AuthenticationScheme,
     Constants,
     THE_FAMILY_ID,
+    ErrorCodeBounds,
 } from "../utils/Constants";
 import { PopTokenGenerator } from "../crypto/PopTokenGenerator";
 import { AppMetadataEntity } from "../cache/entities/AppMetadataEntity";
@@ -151,16 +152,47 @@ export class ResponseHandler {
     /**
      * Function which validates server authorization token response.
      * @param serverResponse
+     * @param refreshAccessToken
      */
     validateTokenResponse(
-        serverResponse: ServerAuthorizationTokenResponse
+        serverResponse: ServerAuthorizationTokenResponse,
+        refreshAccessToken?: boolean
     ): void {
         // Check for error
         if (
             serverResponse.error ||
             serverResponse.error_description ||
             serverResponse.suberror
         ) {
+
+            // check if 500 error
+            if (
+                refreshAccessToken &&
+                serverResponse.status &&
+                (serverResponse.status >= ErrorCodeBounds.stsErrorLowerLimit) &&
+                (serverResponse.status <= ErrorCodeBounds.stsErrorUpperLimit)
+            ) {
+                this.logger.warning(
+                    "executeTokenRequest:validateTokenResponse - AAD is currently unavailable and the access token is unable to be refreshed."
+                );
+
+                // don't throw an exception, but alert the user via a log that the token was unable to be refreshed
+                return;
+            // check if 400 error
+            } else if (
+                refreshAccessToken &&
+                serverResponse.status &&
+                (serverResponse.status >= ErrorCodeBounds.clientErrorLowerLimit) &&
+                (serverResponse.status <= ErrorCodeBounds.clientErrorUpperLimit)
+            ) {
+                this.logger.warning(
+                    "executeTokenRequest:validateTokenResponse - AAD is currently available but is unable to refresh the access token."
+                );
+
+                // don't throw an exception, but alert the user via a log that the token was unable to be refreshed
+                return;
+            }
+
             if (
                 InteractionRequiredAuthError.isInteractionRequiredError(
                     serverResponse.error,
@@ -551,6 +583,7 @@ export class ResponseHandler {
         let responseScopes: Array<string> = [];
         let expiresOn: Date | null = null;
         let extExpiresOn: Date | undefined;
+        let refreshOn: Date | null = null;
         let familyId: string = Constants.EMPTY_STRING;
 
         if (cacheRecord.accessToken) {
@@ -582,6 +615,9 @@ export class ResponseHandler {
             extExpiresOn = new Date(
                 Number(cacheRecord.accessToken.extendedExpiresOn) * 1000
             );
+            refreshOn = new Date(
+                Number(cacheRecord.accessToken.refreshOn) * 1000
+            );
         }
 
         if (cacheRecord.appMetadata) {
@@ -615,9 +651,10 @@ export class ResponseHandler {
             accessToken: accessToken,
             fromCache: fromTokenCache,
             expiresOn: expiresOn,
+            extExpiresOn: extExpiresOn,
+            refreshOn: refreshOn,
             correlationId: request.correlationId,
             requestId: requestId || Constants.EMPTY_STRING,
-            extExpiresOn: extExpiresOn,
             familyId: familyId,
             tokenType:
                 cacheRecord.accessToken?.tokenType || Constants.EMPTY_STRING,

lib/msal-common/src/response/ServerAuthorizationTokenResponse.ts

@@ -24,8 +24,10 @@ import { AuthenticationScheme } from "../utils/Constants";
  * - timestamp: The time at which the error occurred.
  * - trace_id: A unique identifier for the request that can help in diagnostics.
  * - correlation_id: A unique identifier for the request that can help in diagnostics across components.
+ * - status: the network request's response status
  */
 export type ServerAuthorizationTokenResponse = {
+    status?: number;
     // Success
     token_type?: AuthenticationScheme;
     scope?: string;

lib/msal-common/src/utils/Constants.ts

@@ -64,6 +64,14 @@ export const Constants = {
     INVALID_INSTANCE: "invalid_instance",
 };
 
+export const ErrorCodeBounds = {
+    clientErrorLowerLimit: 400,
+    clientErrorUpperLimit: 499,
+    stsErrorLowerLimit: 500,
+    stsErrorUpperLimit: 599,
+} as const;
+export type ErrorCodeBounds = typeof ErrorCodeBounds[keyof typeof ErrorCodeBounds];
+
 export const OIDC_DEFAULT_SCOPES = [
     Constants.OPENID_SCOPE,
     Constants.PROFILE_SCOPE,

lib/msal-common/test/response/ResponseHandler.spec.ts

@@ -110,6 +110,7 @@ const testServerTokenResponse = {
         scope: TEST_CONFIG.DEFAULT_SCOPES.join(" "),
         expires_in: TEST_TOKEN_LIFETIMES.DEFAULT_EXPIRES_IN,
         ext_expires_in: TEST_TOKEN_LIFETIMES.DEFAULT_EXPIRES_IN,
+        refresh_in: TEST_TOKEN_LIFETIMES.DEFAULT_REFESH_IN,
         access_token: TEST_TOKENS.ACCESS_TOKEN,
         refresh_token: TEST_TOKENS.REFRESH_TOKEN,
         id_token: TEST_TOKENS.IDTOKEN_V2,
@@ -265,6 +266,9 @@ describe("ResponseHandler.ts", () => {
                 expiresOn: new Date(
                     Date.now() + testServerTokenResponse.body.expires_in * 1000
                 ),
+                refreshOn: new Date(
+                    Date.now() + testServerTokenResponse.body.refresh_in * 1000
+                ), // one day in the future
                 account: testAccount,
                 tokenType: AuthenticationScheme.BEARER,
             };
@@ -331,6 +335,9 @@ describe("ResponseHandler.ts", () => {
                 expiresOn: new Date(
                     Date.now() + testServerTokenResponse.body.expires_in * 1000
                 ),
+                refreshOn: new Date(
+                    Date.now() + testServerTokenResponse.body.refresh_in * 1000
+                ), // one day in the future
                 account: testAccount,
                 tokenType: AuthenticationScheme.BEARER,
             };
@@ -396,6 +403,9 @@ describe("ResponseHandler.ts", () => {
                 expiresOn: new Date(
                     Date.now() + testServerTokenResponse.body.expires_in * 1000
                 ),
+                refreshOn: new Date(
+                    Date.now() + testServerTokenResponse.body.refresh_in * 1000
+                ), // one day in the future
                 account: testAccount,
                 tokenType: AuthenticationScheme.BEARER,
             };

lib/msal-common/test/test_kit/StringConstants.ts

@@ -73,6 +73,7 @@ export const ID_TOKEN_CLAIMS = {
 // Test Expiration Vals
 export const TEST_TOKEN_LIFETIMES = {
     DEFAULT_EXPIRES_IN: 3599,
+    DEFAULT_REFESH_IN: 86400,
     TEST_ID_TOKEN_EXP: 1536361411,
     TEST_ACCESS_TOKEN_EXP: 1537234948,
 };

lib/msal-node/src/client/ClientCredentialClient.ts

@@ -35,6 +35,7 @@ import {
 export class ClientCredentialClient extends BaseClient {
     private scopeSet: ScopeSet;
     private readonly appTokenProvider?: IAppTokenProvider;
+    private lastCacheOutcome: CacheOutcome;
 
     constructor(
         configuration: ClientConfiguration,
@@ -59,7 +60,23 @@ export class ClientCredentialClient extends BaseClient {
 
         const cachedAuthenticationResult =
             await this.getCachedAuthenticationResult(request);
+
         if (cachedAuthenticationResult) {
+            // if the token is not expired but must be refreshed; get a new one in the background
+            if (this.lastCacheOutcome === CacheOutcome.REFRESH_CACHED_ACCESS_TOKEN) {
+                this.logger.info(
+                    "ClientCredentialClient:getCachedAuthenticationResult - Cached access token's refreshOn property has been exceeded'. It's not expired, but must be refreshed."
+                );
+
+                // return the cached token, don't wait for the result of this request
+                const refreshAccessToken = true;
+                this.executeTokenRequest(request, this.authority, refreshAccessToken);
+            }
+
+            // reset the last cache outcome
+            this.lastCacheOutcome = CacheOutcome.NO_CACHE_HIT;
+
+            // otherwise, the token is not expired and does not need to be refreshed
             return cachedAuthenticationResult;
         } else {
             return await this.executeTokenRequest(request, this.authority);
@@ -78,32 +95,48 @@ export class ClientCredentialClient extends BaseClient {
             cacheContext = new TokenCacheContext(this.config.serializableCache, false);
             await this.config.persistencePlugin.beforeCacheAccess(cacheContext);
         }
-        
+
         const cachedAccessToken = this.readAccessTokenFromCache();
 
         if (this.config.serializableCache && this.config.persistencePlugin && cacheContext) {
             await this.config.persistencePlugin.afterCacheAccess(cacheContext);
         }
 
+        // must refresh due to non-existent access_token
         if (!cachedAccessToken) {
+            this.lastCacheOutcome = CacheOutcome.NO_CACHED_ACCESS_TOKEN;
             this.serverTelemetryManager?.setCacheOutcome(
                 CacheOutcome.NO_CACHED_ACCESS_TOKEN
             );
             return null;
         }
-
+
+        // must refresh due to the expires_in value
         if (
             TimeUtils.isTokenExpired(
                 cachedAccessToken.expiresOn,
                 this.config.systemOptions.tokenRenewalOffsetSeconds
             )
         ) {
+            this.lastCacheOutcome = CacheOutcome.CACHED_ACCESS_TOKEN_EXPIRED;
             this.serverTelemetryManager?.setCacheOutcome(
                 CacheOutcome.CACHED_ACCESS_TOKEN_EXPIRED
             );
+
             return null;
         }
 
+        // must refresh (in the background) due to the refresh_in value
+        if (
+            cachedAccessToken.refreshOn &&
+            TimeUtils.isTokenExpired(cachedAccessToken.refreshOn.toString(), 0)
+        ) {
+            this.lastCacheOutcome = CacheOutcome.REFRESH_CACHED_ACCESS_TOKEN;
+            this.serverTelemetryManager?.setCacheOutcome(
+                CacheOutcome.REFRESH_CACHED_ACCESS_TOKEN
+            );
+        }
+
         return await ResponseHandler.generateAuthenticationResult(
             this.cryptoUtils,
             this.authority,
@@ -150,7 +183,8 @@ export class ClientCredentialClient extends BaseClient {
      */
     private async executeTokenRequest(
         request: CommonClientCredentialRequest,
-        authority: Authority
+        authority: Authority,
+        refreshAccessToken?: boolean,
     ): Promise<AuthenticationResult | null> {
         let serverTokenResponse: ServerAuthorizationTokenResponse;
         let reqTimestamp: number;
@@ -205,7 +239,9 @@ export class ClientCredentialClient extends BaseClient {
                 headers,
                 thumbprint
             );
+
             serverTokenResponse = response.body;
+            serverTokenResponse.status = response.status;
         }
 
         const responseHandler = new ResponseHandler(
@@ -217,7 +253,7 @@ export class ClientCredentialClient extends BaseClient {
             this.config.persistencePlugin
         );
 
-        responseHandler.validateTokenResponse(serverTokenResponse);
+        responseHandler.validateTokenResponse(serverTokenResponse, refreshAccessToken);
 
         const tokenResponse = await responseHandler.handleServerTokenResponse(
             serverTokenResponse,