@azure/msal-common 14.0.3 → 14.1.0

package/src/client/SilentFlowClient.ts

@@ -11,9 +11,13 @@ import { TimeUtils } from "../utils/TimeUtils";
 import { RefreshTokenClient } from "./RefreshTokenClient";
 import {
     ClientAuthError,
-    ClientAuthErrorMessage,
+    ClientAuthErrorCodes,
+    createClientAuthError,
 } from "../error/ClientAuthError";
-import { ClientConfigurationError } from "../error/ClientConfigurationError";
+import {
+    createClientConfigurationError,
+    ClientConfigurationErrorCodes,
+} from "../error/ClientConfigurationError";
 import { ResponseHandler } from "../response/ResponseHandler";
 import { CacheRecord } from "../cache/entities/CacheRecord";
 import { CacheOutcome } from "../utils/Constants";
@@ -40,11 +44,35 @@ export class SilentFlowClient extends BaseClient {
         request: CommonSilentFlowRequest
     ): Promise<AuthenticationResult> {
         try {
-            return await this.acquireCachedToken(request);
+            const [authResponse, cacheOutcome] = await this.acquireCachedToken(
+                request
+            );
+
+            // if the token is not expired but must be refreshed; get a new one in the background
+            if (cacheOutcome === CacheOutcome.PROACTIVELY_REFRESHED) {
+                this.logger.info(
+                    "SilentFlowClient:acquireCachedToken - Cached access token's refreshOn property has been exceeded'. It's not expired, but must be refreshed."
+                );
+
+                // refresh the access token in the background
+                const refreshTokenClient = new RefreshTokenClient(
+                    this.config,
+                    this.performanceClient
+                );
+
+                refreshTokenClient
+                    .acquireTokenByRefreshToken(request)
+                    .catch(() => {
+                        // do nothing, this is running in the background and no action is to be taken upon success or failure
+                    });
+            }
+
+            // return the cached token
+            return authResponse;
         } catch (e) {
             if (
                 e instanceof ClientAuthError &&
-                e.errorCode === ClientAuthErrorMessage.tokenRefreshRequired.code
+                e.errorCode === ClientAuthErrorCodes.tokenRefreshRequired
             ) {
                 const refreshTokenClient = new RefreshTokenClient(
                     this.config,
@@ -63,35 +91,47 @@ export class SilentFlowClient extends BaseClient {
      */
     async acquireCachedToken(
         request: CommonSilentFlowRequest
-    ): Promise<AuthenticationResult> {
+    ): Promise<[AuthenticationResult, CacheOutcome]> {
+        let lastCacheOutcome: CacheOutcome = CacheOutcome.NOT_APPLICABLE;
+
         // Cannot renew token if no request object is given.
         if (!request) {
-            throw ClientConfigurationError.createEmptyTokenRequestError();
+            throw createClientConfigurationError(
+                ClientConfigurationErrorCodes.tokenRequestEmpty
+            );
         }
 
         if (request.forceRefresh) {
             // Must refresh due to present force_refresh flag.
+            lastCacheOutcome = CacheOutcome.FORCE_REFRESH_OR_CLAIMS;
             this.serverTelemetryManager?.setCacheOutcome(
-                CacheOutcome.FORCE_REFRESH
+                CacheOutcome.FORCE_REFRESH_OR_CLAIMS
             );
             this.logger.info(
                 "SilentFlowClient:acquireCachedToken - Skipping cache because forceRefresh is true."
             );
-            throw ClientAuthError.createRefreshRequiredError();
+            throw createClientAuthError(
+                ClientAuthErrorCodes.tokenRefreshRequired
+            );
         } else if (
             !this.config.cacheOptions.claimsBasedCachingEnabled &&
             !StringUtils.isEmptyObj(request.claims)
         ) {
+            lastCacheOutcome = CacheOutcome.FORCE_REFRESH_OR_CLAIMS;
             // Must refresh due to request parameters.
             this.logger.info(
                 "SilentFlowClient:acquireCachedToken - Skipping cache because claims-based caching is disabled and claims were requested."
             );
-            throw ClientAuthError.createRefreshRequiredError();
+            throw createClientAuthError(
+                ClientAuthErrorCodes.tokenRefreshRequired
+            );
         }
 
         // We currently do not support silent flow for account === null use cases; This will be revisited for confidential flow usecases
         if (!request.account) {
-            throw ClientAuthError.createNoAccountInSilentRequestError();
+            throw createClientAuthError(
+                ClientAuthErrorCodes.noAccountInSilentRequest
+            );
         }
 
         const environment =
@@ -104,14 +144,17 @@ export class SilentFlowClient extends BaseClient {
         );
 
         if (!cacheRecord.accessToken) {
-            // Must refresh due to non-existent access_token.
+            // must refresh due to non-existent access_token
+            lastCacheOutcome = CacheOutcome.NO_CACHED_ACCESS_TOKEN;
             this.serverTelemetryManager?.setCacheOutcome(
                 CacheOutcome.NO_CACHED_ACCESS_TOKEN
             );
             this.logger.info(
                 "SilentFlowClient:acquireCachedToken - No access token found in cache for the given properties."
             );
-            throw ClientAuthError.createRefreshRequiredError();
+            throw createClientAuthError(
+                ClientAuthErrorCodes.tokenRefreshRequired
+            );
         } else if (
             TimeUtils.wasClockTurnedBack(cacheRecord.accessToken.cachedAt) ||
             TimeUtils.isTokenExpired(
@@ -119,33 +162,41 @@ export class SilentFlowClient extends BaseClient {
                 this.config.systemOptions.tokenRenewalOffsetSeconds
             )
         ) {
-            // Must refresh due to expired access_token.
+            // must refresh due to the expires_in value
+            lastCacheOutcome = CacheOutcome.CACHED_ACCESS_TOKEN_EXPIRED;
             this.serverTelemetryManager?.setCacheOutcome(
                 CacheOutcome.CACHED_ACCESS_TOKEN_EXPIRED
             );
             this.logger.info(
                 `SilentFlowClient:acquireCachedToken - Cached access token is expired or will expire within ${this.config.systemOptions.tokenRenewalOffsetSeconds} seconds.`
             );
-            throw ClientAuthError.createRefreshRequiredError();
+            throw createClientAuthError(
+                ClientAuthErrorCodes.tokenRefreshRequired
+            );
         } else if (
             cacheRecord.accessToken.refreshOn &&
             TimeUtils.isTokenExpired(cacheRecord.accessToken.refreshOn, 0)
         ) {
-            // Must refresh due to the refresh_in value.
+            // must refresh (in the background) due to the refresh_in value
+            lastCacheOutcome = CacheOutcome.PROACTIVELY_REFRESHED;
             this.serverTelemetryManager?.setCacheOutcome(
-                CacheOutcome.REFRESH_CACHED_ACCESS_TOKEN
+                CacheOutcome.PROACTIVELY_REFRESHED
             );
             this.logger.info(
                 "SilentFlowClient:acquireCachedToken - Cached access token's refreshOn property has been exceeded'."
             );
-            throw ClientAuthError.createRefreshRequiredError();
+
+            // don't throw ClientAuthError.createRefreshRequiredError(), return cached token instead
         }
 
         if (this.config.serverTelemetryManager) {
             this.config.serverTelemetryManager.incrementCacheHits();
         }
 
-        return await this.generateResultFromCacheRecord(cacheRecord, request);
+        return [
+            await this.generateResultFromCacheRecord(cacheRecord, request),
+            lastCacheOutcome,
+        ];
     }
 
     /**
@@ -168,7 +219,9 @@ export class SilentFlowClient extends BaseClient {
         if (request.maxAge || request.maxAge === 0) {
             const authTime = idTokenClaims?.auth_time;
             if (!authTime) {
-                throw ClientAuthError.createAuthTimeNotFoundError();
+                throw createClientAuthError(
+                    ClientAuthErrorCodes.authTimeNotFound
+                );
             }
 
             checkMaxAge(authTime, request.maxAge);

package/src/config/ClientConfiguration.ts

@@ -5,7 +5,6 @@
 
 import { INetworkModule } from "../network/INetworkModule";
 import { DEFAULT_CRYPTO_IMPLEMENTATION, ICrypto } from "../crypto/ICrypto";
-import { AuthError } from "../error/AuthError";
 import { ILoggerCallback, Logger, LogLevel } from "../logger/Logger";
 import { Constants } from "../utils/Constants";
 import { version } from "../packageMetadata";
@@ -17,6 +16,10 @@ import { ICachePlugin } from "../cache/interface/ICachePlugin";
 import { ISerializableTokenCache } from "../cache/interface/ISerializableTokenCache";
 import { ClientCredentials } from "../account/ClientCredentials";
 import { ProtocolMode } from "../authority/ProtocolMode";
+import {
+    ClientAuthErrorCodes,
+    createClientAuthError,
+} from "../error/ClientAuthError";
 
 // Token renewal offset default in seconds
 const DEFAULT_TOKEN_RENEWAL_OFFSET_SEC = 300;
@@ -177,14 +180,10 @@ const DEFAULT_CACHE_OPTIONS: Required<CacheOptions> = {
 
 const DEFAULT_NETWORK_IMPLEMENTATION: INetworkModule = {
     async sendGetRequestAsync<T>(): Promise<T> {
-        const notImplErr =
-            "Network interface - sendGetRequestAsync() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
+        throw createClientAuthError(ClientAuthErrorCodes.methodNotImplemented);
     },
     async sendPostRequestAsync<T>(): Promise<T> {
-        const notImplErr =
-            "Network interface - sendPostRequestAsync() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
+        throw createClientAuthError(ClientAuthErrorCodes.methodNotImplemented);
     },
 };
 

package/src/crypto/ICrypto.ts

@@ -3,7 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { AuthError } from "../error/AuthError";
+import {
+    ClientAuthErrorCodes,
+    createClientAuthError,
+} from "../error/ClientAuthError";
 import { BaseAuthRequest } from "../request/BaseAuthRequest";
 import { SignedHttpRequest } from "./SignedHttpRequest";
 
@@ -42,10 +45,6 @@ export interface ICrypto {
      * @param input
      */
     base64Decode(input: string): string;
-    /**
-     * Generate PKCE codes for OAuth. See RFC here: https://tools.ietf.org/html/rfc7636
-     */
-    generatePkceCodes(): Promise<PkceCodes>;
     /**
      * Generates an JWK RSA S256 Thumbprint
      * @param request
@@ -80,48 +79,27 @@ export interface ICrypto {
 
 export const DEFAULT_CRYPTO_IMPLEMENTATION: ICrypto = {
     createNewGuid: (): string => {
-        const notImplErr =
-            "Crypto interface - createNewGuid() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
+        throw createClientAuthError(ClientAuthErrorCodes.methodNotImplemented);
     },
     base64Decode: (): string => {
-        const notImplErr =
-            "Crypto interface - base64Decode() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
+        throw createClientAuthError(ClientAuthErrorCodes.methodNotImplemented);
     },
     base64Encode: (): string => {
-        const notImplErr =
-            "Crypto interface - base64Encode() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
-    },
-    async generatePkceCodes(): Promise<PkceCodes> {
-        const notImplErr =
-            "Crypto interface - generatePkceCodes() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
+        throw createClientAuthError(ClientAuthErrorCodes.methodNotImplemented);
     },
     async getPublicKeyThumbprint(): Promise<string> {
-        const notImplErr =
-            "Crypto interface - getPublicKeyThumbprint() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
+        throw createClientAuthError(ClientAuthErrorCodes.methodNotImplemented);
     },
     async removeTokenBindingKey(): Promise<boolean> {
-        const notImplErr =
-            "Crypto interface - removeTokenBindingKey() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
+        throw createClientAuthError(ClientAuthErrorCodes.methodNotImplemented);
     },
     async clearKeystore(): Promise<boolean> {
-        const notImplErr =
-            "Crypto interface - clearKeystore() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
+        throw createClientAuthError(ClientAuthErrorCodes.methodNotImplemented);
     },
     async signJwt(): Promise<string> {
-        const notImplErr =
-            "Crypto interface - signJwt() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
+        throw createClientAuthError(ClientAuthErrorCodes.methodNotImplemented);
     },
     async hashString(): Promise<string> {
-        const notImplErr =
-            "Crypto interface - hashString() has not been implemented";
-        throw AuthError.createUnexpectedError(notImplErr);
+        throw createClientAuthError(ClientAuthErrorCodes.methodNotImplemented);
     },
 };

package/src/crypto/JoseHeader.ts

@@ -3,7 +3,10 @@
  * Licensed under the MIT License.
  */
 
-import { JoseHeaderError } from "../error/JoseHeaderError";
+import {
+    JoseHeaderErrorCodes,
+    createJoseHeaderError,
+} from "../error/JoseHeaderError";
 import { JsonTypes } from "../utils/Constants";
 
 export type JoseHeaderOptions = {
@@ -35,12 +38,12 @@ export class JoseHeader {
     static getShrHeaderString(shrHeaderOptions: JoseHeaderOptions): string {
         // KeyID is required on the SHR header
         if (!shrHeaderOptions.kid) {
-            throw JoseHeaderError.createMissingKidError();
+            throw createJoseHeaderError(JoseHeaderErrorCodes.missingKidError);
         }
 
         // Alg is required on the SHR header
         if (!shrHeaderOptions.alg) {
-            throw JoseHeaderError.createMissingAlgError();
+            throw createJoseHeaderError(JoseHeaderErrorCodes.missingAlgError);
         }
 
         const shrHeader = new JoseHeader({

package/src/crypto/PopTokenGenerator.ts

@@ -8,6 +8,8 @@ import { TimeUtils } from "../utils/TimeUtils";
 import { UrlString } from "../url/UrlString";
 import { IPerformanceClient } from "../telemetry/performance/IPerformanceClient";
 import { PerformanceEvents } from "../telemetry/performance/PerformanceEvent";
+import { invokeAsync } from "../utils/FunctionWrappers";
+import { Logger } from "../logger/Logger";
 
 /**
  * See eSTS docs for more info.
@@ -50,18 +52,21 @@ export class PopTokenGenerator {
      * @returns
      */
     async generateCnf(
-        request: SignedHttpRequestParameters
+        request: SignedHttpRequestParameters,
+        logger: Logger
     ): Promise<ReqCnfData> {
         this.performanceClient?.addQueueMeasurement(
             PerformanceEvents.PopTokenGenerateCnf,
             request.correlationId
         );
 
-        this.performanceClient?.setPreQueueTime(
-            PerformanceEvents.PopTokenGenerateKid,
+        const reqCnf = await invokeAsync(
+            this.generateKid.bind(this),
+            PerformanceEvents.PopTokenGenerateCnf,
+            logger,
+            this.performanceClient,
             request.correlationId
-        );
-        const reqCnf = await this.generateKid(request);
+        )(request);
         const reqCnfString: string = this.cryptoUtils.base64Encode(
             JSON.stringify(reqCnf)
         );

package/src/error/AuthError.ts

@@ -4,18 +4,27 @@
  */
 
 import { Constants } from "../utils/Constants";
+import * as AuthErrorCodes from "./AuthErrorCodes";
+export { AuthErrorCodes };
+
+export const AuthErrorMessages = {
+    [AuthErrorCodes.unexpectedError]: "Unexpected error in authentication.",
+    [AuthErrorCodes.postRequestFailed]:
+        "Post request failed from the network, could be a 4xx/5xx or a network unavailability. Please check the exact error code for details.",
+};
 
 /**
  * AuthErrorMessage class containing string constants used by error codes and messages.
+ * @deprecated Use AuthErrorCodes instead
  */
 export const AuthErrorMessage = {
     unexpectedError: {
-        code: "unexpected_error",
-        desc: "Unexpected error in authentication.",
+        code: AuthErrorCodes.unexpectedError,
+        desc: AuthErrorMessages[AuthErrorCodes.unexpectedError],
     },
     postRequestFailed: {
-        code: "post_request_failed",
-        desc: "Post request failed from the network, could be a 4xx/5xx or a network unavailability. Please check the exact error code for details.",
+        code: AuthErrorCodes.postRequestFailed,
+        desc: AuthErrorMessages[AuthErrorCodes.postRequestFailed],
     },
 };
 
@@ -59,27 +68,16 @@ export class AuthError extends Error {
     setCorrelationId(correlationId: string): void {
         this.correlationId = correlationId;
     }
+}
 
-    /**
-     * Creates an error that is thrown when something unexpected happens in the library.
-     * @param errDesc
-     */
-    static createUnexpectedError(errDesc: string): AuthError {
-        return new AuthError(
-            AuthErrorMessage.unexpectedError.code,
-            `${AuthErrorMessage.unexpectedError.desc}: ${errDesc}`
-        );
-    }
-
-    /**
-     * Creates an error for post request failures.
-     * @param errDesc
-     * @returns
-     */
-    static createPostRequestFailed(errDesc: string): AuthError {
-        return new AuthError(
-            AuthErrorMessage.postRequestFailed.code,
-            `${AuthErrorMessage.postRequestFailed.desc}: ${errDesc}`
-        );
-    }
+export function createAuthError(
+    code: string,
+    additionalMessage?: string
+): AuthError {
+    return new AuthError(
+        code,
+        additionalMessage
+            ? `${AuthErrorMessages[code]} ${additionalMessage}`
+            : AuthErrorMessages[code]
+    );
 }

package/src/error/AuthErrorCodes.ts

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * AuthErrorMessage class containing string constants used by error codes and messages.
+ */
+export const unexpectedError = "unexpected_error";
+export const postRequestFailed = "post_request_failed";