@azure/msal-common 16.9.0 → 16.11.0

package/src/request/BaseAuthRequest.ts

@@ -69,6 +69,10 @@ export type BaseAuthRequest = {
     azureCloudOptions?: AzureCloudOptions;
     /**
      * Maximum allowed age, in milliseconds, of the user's authentication before a new sign-in is required.
+     * @deprecated This option no longer has any effect and will be removed in a future major version.
+     * MSAL does not validate the authentication age of returned tokens. To enforce the OIDC `max_age`
+     * parameter, send it via `extraQueryParameters` and validate the `auth_time` claim of the returned
+     * token yourself.
      */
     maxAge?: number;
     /**
@@ -130,13 +134,15 @@ export function enforceResourceParameter(
             containsResourceParam(request.extraQueryParameters))
     ) {
         throw createClientAuthError(
-            ClientAuthErrorCodes.misplacedResourceParam
+            ClientAuthErrorCodes.misplacedResourceParam,
+            request.correlationId || ""
         );
     }
 
     if (!request.resource) {
         throw createClientAuthError(
-            ClientAuthErrorCodes.resourceParameterRequired
+            ClientAuthErrorCodes.resourceParameterRequired,
+            request.correlationId || ""
         );
     }
 }

package/src/request/RequestParameterBuilder.ts

@@ -18,7 +18,6 @@ import {
 import { ServerTelemetryManager } from "../telemetry/server/ServerTelemetryManager.js";
 import { ClientInfo } from "../account/ClientInfo.js";
 import { IPerformanceClient } from "../telemetry/performance/IPerformanceClient.js";
-import { StringUtils } from "../utils/StringUtils.js";
 
 export function instrumentBrokerParams(
     parameters: Map<string, string>,
@@ -84,6 +83,7 @@ export function addNativeBroker(parameters: Map<string, string>): void {
 export function addScopes(
     parameters: Map<string, string>,
     scopes: string[],
+    correlationId: string,
     addOidcScopes: boolean = true,
     defaultScopes: Array<string> = Constants.OIDC_DEFAULT_SCOPES
 ): void {
@@ -98,7 +98,7 @@ export function addScopes(
     const requestScopes = addOidcScopes
         ? [...(scopes || []), ...defaultScopes]
         : scopes || [];
-    const scopeSet = new ScopeSet(requestScopes);
+    const scopeSet = new ScopeSet(requestScopes, correlationId);
     parameters.set(AADServerParamKeys.SCOPE, scopeSet.printScopes());
 }
 
@@ -205,12 +205,14 @@ export function addSid(parameters: Map<string, string>, sid: string): void {
  * Adds claims to request parameters, conditionally excluding clientCapabilities
  * when skipBrokerClaims is true and a brokered flow is in effect.
  * @param parameters - The request parameters map
+ * @param correlationId - The request correlation id
  * @param claims - The claims string from the request
  * @param clientCapabilities - The client capabilities from configuration
  * @param skipBrokerClaims - When true and BROKER_CLIENT_ID is present, excludes clientCapabilities from claims
  */
 export function addClaims(
     parameters: Map<string, string>,
+    correlationId: string,
     claims?: string,
     clientCapabilities?: Array<string>,
     skipBrokerClaims?: boolean
@@ -221,23 +223,8 @@ export function addClaims(
             ? undefined
             : clientCapabilities;
 
-    if (
-        !StringUtils.isEmptyObj(claims) ||
-        (configClaims && configClaims.length > 0)
-    ) {
-        const mergedClaims = addClientCapabilitiesToClaims(
-            claims,
-            configClaims
-        );
-        try {
-            JSON.parse(mergedClaims);
-        } catch (e) {
-            throw createClientConfigurationError(
-                ClientConfigurationErrorCodes.invalidClaims
-            );
-        }
-        parameters.set(AADServerParamKeys.CLAIMS, mergedClaims);
-    }
+    const mergedClaims = buildMergedClaims(claims, configClaims, correlationId);
+    parameters.set(AADServerParamKeys.CLAIMS, mergedClaims);
 }
 
 /**
@@ -335,7 +322,8 @@ export function addCodeChallengeParams(
         );
     } else {
         throw createClientConfigurationError(
-            ClientConfigurationErrorCodes.pkceParamsMissing
+            ClientConfigurationErrorCodes.pkceParamsMissing,
+            ""
         );
     }
 }
@@ -493,9 +481,27 @@ export function addExtraParameters(
     });
 }
 
-export function addClientCapabilitiesToClaims(
+/**
+ * Default optional idToken claims requested on all auth requests.
+ * signin_state enables KMSI detection; login_hint enables login hint propagation.
+ */
+const DEFAULT_ID_TOKEN_CLAIMS: Record<string, { essential: false }> = {
+    [Constants.ClaimsRequestKeys.SIGNIN_STATE]: { essential: false },
+    [Constants.ClaimsRequestKeys.LOGIN_HINT]: { essential: false },
+};
+
+/**
+ * Parses claims JSON, merges default optional idToken claims (signin_state, login_hint),
+ * and appends client capabilities (xms_cc) to the access_token section.
+ * Does not overwrite idToken claims already specified by the caller.
+ * @param claims - Existing claims JSON string from the request (may be undefined)
+ * @param clientCapabilities - Client capabilities array from configuration
+ * @returns Merged claims JSON string
+ */
+export function buildMergedClaims(
     claims?: string,
-    clientCapabilities?: Array<string>
+    clientCapabilities?: Array<string>,
+    correlationId: string = ""
 ): string {
     let mergedClaims: object;
 
@@ -504,17 +510,44 @@ export function addClientCapabilitiesToClaims(
         mergedClaims = {};
     } else {
         try {
-            mergedClaims = JSON.parse(claims);
+            const parsed = JSON.parse(claims);
+            if (
+                typeof parsed !== "object" ||
+                parsed === null ||
+                Array.isArray(parsed)
+            ) {
+                throw new Error("Claims must be a JSON object");
+            }
+            mergedClaims = parsed;
         } catch (e) {
             throw createClientConfigurationError(
-                ClientConfigurationErrorCodes.invalidClaims
+                ClientConfigurationErrorCodes.invalidClaims,
+                correlationId
             );
         }
     }
 
+    // Add default optional idToken claims
+    if (
+        !Object.prototype.hasOwnProperty.call(
+            mergedClaims,
+            Constants.ClaimsRequestKeys.ID_TOKEN
+        )
+    ) {
+        mergedClaims[Constants.ClaimsRequestKeys.ID_TOKEN] = {};
+    }
+    const idTokenClaims = mergedClaims[Constants.ClaimsRequestKeys.ID_TOKEN];
+    for (const [key, value] of Object.entries(DEFAULT_ID_TOKEN_CLAIMS)) {
+        if (!(key in idTokenClaims)) {
+            idTokenClaims[key] = value;
+        }
+    }
+
+    // Add client capabilities
     if (clientCapabilities && clientCapabilities.length > 0) {
         if (
-            !mergedClaims.hasOwnProperty(
+            !Object.prototype.hasOwnProperty.call(
+                mergedClaims,
                 Constants.ClaimsRequestKeys.ACCESS_TOKEN
             )
         ) {
@@ -597,24 +630,14 @@ export function addServerTelemetry(
     parameters: Map<string, string>,
     serverTelemetryManager: ServerTelemetryManager
 ): void {
-    const currentTelemetryHeader =
-        serverTelemetryManager.generateCurrentRequestHeaderValue();
-    const lastTelemetryHeader =
-        serverTelemetryManager.generateLastRequestHeaderValue();
-
-    if (currentTelemetryHeader) {
-        parameters.set(
-            AADServerParamKeys.X_CLIENT_CURR_TELEM,
-            currentTelemetryHeader
-        );
-    }
-
-    if (lastTelemetryHeader) {
-        parameters.set(
-            AADServerParamKeys.X_CLIENT_LAST_TELEM,
-            lastTelemetryHeader
-        );
-    }
+    parameters.set(
+        AADServerParamKeys.X_CLIENT_CURR_TELEM,
+        serverTelemetryManager.generateCurrentRequestHeaderValue()
+    );
+    parameters.set(
+        AADServerParamKeys.X_CLIENT_LAST_TELEM,
+        serverTelemetryManager.generateLastRequestHeaderValue()
+    );
 }
 
 /**

package/src/request/ScopeSet.ts

@@ -26,8 +26,10 @@ import {
 export class ScopeSet {
     // Scopes as a Set of strings
     private scopes: Set<string>;
+    private correlationId: string;
 
-    constructor(inputScopes: Array<string>) {
+    constructor(inputScopes: Array<string>, correlationId: string) {
+        this.correlationId = correlationId;
         // Filter empty string and null/undefined array items
         const scopeArr = inputScopes
             ? StringUtils.trimArrayEntries([...inputScopes])
@@ -39,7 +41,8 @@ export class ScopeSet {
         // Check if scopes array has at least one member
         if (!filteredInput || !filteredInput.length) {
             throw createClientConfigurationError(
-                ClientConfigurationErrorCodes.emptyInputScopesError
+                ClientConfigurationErrorCodes.emptyInputScopesError,
+                correlationId
             );
         }
 
@@ -53,10 +56,13 @@ export class ScopeSet {
      * @param appClientId
      * @param scopesRequired
      */
-    static fromString(inputScopeString: string): ScopeSet {
+    static fromString(
+        inputScopeString: string,
+        correlationId: string
+    ): ScopeSet {
         const scopeString = inputScopeString || "";
         const inputScopes: Array<string> = scopeString.split(" ");
-        return new ScopeSet(inputScopes);
+        return new ScopeSet(inputScopes, correlationId);
     }
 
     /**
@@ -64,14 +70,17 @@ export class ScopeSet {
      * @param inputScopeString
      * @returns
      */
-    static createSearchScopes(inputScopeString: Array<string>): ScopeSet {
+    static createSearchScopes(
+        inputScopeString: Array<string>,
+        correlationId: string
+    ): ScopeSet {
         // Handle empty scopes by using default OIDC scopes for cache lookup
         const scopesToUse =
             inputScopeString && inputScopeString.length > 0
                 ? inputScopeString
                 : [...OIDC_DEFAULT_SCOPES];
 
-        const scopeSet = new ScopeSet(scopesToUse);
+        const scopeSet = new ScopeSet(scopesToUse, correlationId);
         if (!scopeSet.containsOnlyOIDCScopes()) {
             scopeSet.removeOIDCScopes();
         } else {
@@ -87,7 +96,10 @@ export class ScopeSet {
      */
     containsScope(scope: string): boolean {
         const lowerCaseScopes = this.printScopesLowerCase().split(" ");
-        const lowerCaseScopesSet = new ScopeSet(lowerCaseScopes);
+        const lowerCaseScopesSet = new ScopeSet(
+            lowerCaseScopes,
+            this.correlationId
+        );
         // compare lowercase scopes
         return scope
             ? lowerCaseScopesSet.scopes.has(scope.toLowerCase())
@@ -142,7 +154,8 @@ export class ScopeSet {
             newScopes.forEach((newScope) => this.appendScope(newScope));
         } catch (e) {
             throw createClientAuthError(
-                ClientAuthErrorCodes.cannotAppendScopeSet
+                ClientAuthErrorCodes.cannotAppendScopeSet,
+                this.correlationId
             );
         }
     }
@@ -154,7 +167,8 @@ export class ScopeSet {
     removeScope(scope: string): void {
         if (!scope) {
             throw createClientAuthError(
-                ClientAuthErrorCodes.cannotRemoveEmptyScope
+                ClientAuthErrorCodes.cannotRemoveEmptyScope,
+                this.correlationId
             );
         }
         this.scopes.delete(scope.trim());
@@ -177,7 +191,8 @@ export class ScopeSet {
     unionScopeSets(otherScopes: ScopeSet): Set<string> {
         if (!otherScopes) {
             throw createClientAuthError(
-                ClientAuthErrorCodes.emptyInputScopeSet
+                ClientAuthErrorCodes.emptyInputScopeSet,
+                this.correlationId
             );
         }
         const unionScopes = new Set<string>(); // Iterator in constructor not supported in IE11
@@ -195,7 +210,8 @@ export class ScopeSet {
     intersectingScopeSets(otherScopes: ScopeSet): boolean {
         if (!otherScopes) {
             throw createClientAuthError(
-                ClientAuthErrorCodes.emptyInputScopeSet
+                ClientAuthErrorCodes.emptyInputScopeSet,
+                this.correlationId
             );
         }
 

package/src/response/ImdsComputeResponse.ts

@@ -0,0 +1,14 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Response body returned by the IMDS compute metadata endpoint
+ * (http://169.254.169.254/metadata/instance/compute). Only the `location`
+ * field is used for region auto-discovery. `location` is optional because the
+ * IMDS response can legitimately omit it or return `null`.
+ */
+export type ImdsComputeResponse = {
+    location?: string;
+};

package/src/response/ResponseHandler.ts

@@ -8,11 +8,7 @@ import {
     buildTenantProfile,
     updateAccountTenantProfileData,
 } from "../account/AccountInfo.js";
-import {
-    checkMaxAge,
-    extractTokenClaims,
-    isKmsi,
-} from "../account/AuthToken.js";
+import { extractTokenClaims, isKmsi } from "../account/AuthToken.js";
 import {
     TokenClaims,
     getTenantIdFromIdTokenClaims,
@@ -117,7 +113,8 @@ export class ResponseHandler {
                 ? serverResponse.error_codes[0]
                 : undefined;
             const serverError = new ServerError(
-                serverResponse.error,
+                serverResponse.error || "",
+                serverResponse.correlation_id || "",
                 errString,
                 serverResponse.suberror,
                 serverErrorNo,
@@ -164,12 +161,12 @@ export class ResponseHandler {
                 )
             ) {
                 throw new InteractionRequiredAuthError(
-                    serverResponse.error,
+                    serverResponse.error || "",
+                    serverResponse.correlation_id || "",
                     serverResponse.error_description,
                     serverResponse.suberror,
                     serverResponse.timestamp || "",
                     serverResponse.trace_id || "",
-                    serverResponse.correlation_id || "",
                     serverResponse.claims || "",
                     serverErrorNo
                 );
@@ -194,35 +191,26 @@ export class ResponseHandler {
         userAssertionHash?: string,
         handlingRefreshTokenResponse?: boolean,
         forceCacheRefreshTokenResponse?: boolean,
-        serverRequestId?: string
+        serverRequestId?: string,
+        additionalCacheKeyComponents?: Record<string, string>
     ): Promise<AuthenticationResult> {
         // create an idToken object (not entity)
         let idTokenClaims: TokenClaims | undefined;
         if (serverTokenResponse.id_token) {
             idTokenClaims = extractTokenClaims(
                 serverTokenResponse.id_token || "",
-                this.cryptoObj.base64Decode
+                this.cryptoObj.base64Decode,
+                request.correlationId
             );
 
             // token nonce check (TODO: Add a warning if no nonce is given?)
             if (authCodePayload && authCodePayload.nonce) {
                 if (idTokenClaims.nonce !== authCodePayload.nonce) {
                     throw createClientAuthError(
-                        ClientAuthErrorCodes.nonceMismatch
-                    );
-                }
-            }
-
-            // token max_age check
-            if (request.maxAge || request.maxAge === 0) {
-                const authTime = idTokenClaims.auth_time;
-                if (!authTime) {
-                    throw createClientAuthError(
-                        ClientAuthErrorCodes.authTimeNotFound
+                        ClientAuthErrorCodes.nonceMismatch,
+                        request.correlationId
                     );
                 }
-
-                checkMaxAge(authTime, request.maxAge);
             }
         }
 
@@ -241,7 +229,8 @@ export class ResponseHandler {
         if (!!authCodePayload && !!authCodePayload.state) {
             requestStateObj = ProtocolUtils.parseRequestState(
                 this.cryptoObj.base64Decode,
-                authCodePayload.state
+                authCodePayload.state,
+                request.correlationId
             );
         }
 
@@ -256,7 +245,8 @@ export class ResponseHandler {
             request,
             idTokenClaims,
             userAssertionHash,
-            authCodePayload
+            authCodePayload,
+            additionalCacheKeyComponents
         );
         let cacheContext;
         try {
@@ -363,12 +353,14 @@ export class ResponseHandler {
         request: BaseAuthRequest,
         idTokenClaims?: TokenClaims,
         userAssertionHash?: string,
-        authCodePayload?: AuthorizationCodePayload
+        authCodePayload?: AuthorizationCodePayload,
+        additionalCacheKeyComponents?: Record<string, string>
     ): CacheRecord {
         const env = authority.getPreferredCache();
         if (!env) {
             throw createClientAuthError(
-                ClientAuthErrorCodes.invalidCacheEnvironment
+                ClientAuthErrorCodes.invalidCacheEnvironment,
+                request.correlationId
             );
         }
 
@@ -408,8 +400,11 @@ export class ResponseHandler {
         if (serverTokenResponse.access_token) {
             // If scopes not returned in server response, use request scopes
             const responseScopes = serverTokenResponse.scope
-                ? ScopeSet.fromString(serverTokenResponse.scope)
-                : new ScopeSet(request.scopes || []);
+                ? ScopeSet.fromString(
+                      serverTokenResponse.scope,
+                      request.correlationId
+                  )
+                : new ScopeSet(request.scopes || [], request.correlationId);
 
             /*
              * Use timestamp calculated before request
@@ -446,10 +441,12 @@ export class ResponseHandler {
                 tokenExpirationSeconds,
                 extendedTokenExpirationSeconds,
                 this.cryptoObj.base64Decode,
+                request.correlationId,
                 refreshOnSeconds,
                 serverTokenResponse.token_type,
                 userAssertionHash,
-                serverTokenResponse.key_id
+                serverTokenResponse.key_id,
+                additionalCacheKeyComponents
             );
             // Set resource (to be used for MCP scenarios)
             const resource = request.resource || null;
@@ -553,7 +550,8 @@ export class ResponseHandler {
 
                 if (!keyId) {
                     throw createClientAuthError(
-                        ClientAuthErrorCodes.keyIdMissing
+                        ClientAuthErrorCodes.keyIdMissing,
+                        request.correlationId
                     );
                 }
 
@@ -566,7 +564,8 @@ export class ResponseHandler {
                 accessToken = cacheRecord.accessToken.secret;
             }
             responseScopes = ScopeSet.fromString(
-                cacheRecord.accessToken.target
+                cacheRecord.accessToken.target,
+                request.correlationId
             ).asArray();
             // Access token expiresOn cached in seconds, converting to Date for AuthenticationResult
             expiresOn = TimeUtils.toDateFromSeconds(
@@ -593,8 +592,20 @@ export class ResponseHandler {
 
         // for hybrid + native bridge enablement, send back the native account Id
         if (serverTokenResponse?.spa_accountid && !!cacheRecord.account) {
+            // Set on deprecated top-level for downgrade compat
             cacheRecord.account.nativeAccountId =
                 serverTokenResponse?.spa_accountid;
+            // Set on the matching tenant profile (source of truth)
+            const targetTenantId = tid || cacheRecord.account.realm;
+            if (cacheRecord.account.tenantProfiles) {
+                const matchingProfile = cacheRecord.account.tenantProfiles.find(
+                    (tp) => tp.tenantId === targetTenantId
+                );
+                if (matchingProfile) {
+                    matchingProfile.nativeAccountId =
+                        serverTokenResponse.spa_accountid;
+                }
+            }
         }
 
         const accountInfo: AccountInfo | null = cacheRecord.account
@@ -692,6 +703,7 @@ export function buildAccountToCache(
                 nativeAccountId: nativeAccountId,
             },
             authority,
+            correlationId,
             base64Decode
         );
 
@@ -707,6 +719,7 @@ export function buildAccountToCache(
             homeAccountId,
             baseAccount.localAccountId,
             tenantId,
+            nativeAccountId,
             idTokenClaims
         );
         tenantProfiles.push(newTenantProfile);

package/src/telemetry/performance/IPerformanceClient.ts

@@ -31,6 +31,7 @@ export interface IPerformanceClient {
         fields: { [key: string]: {} | undefined },
         correlationId: string
     ): void;
+    addGlobalFields(fields: { [key: string]: {} | undefined }): void;
     incrementFields(
         fields: { [key: string]: number | undefined },
         correlationId: string

package/src/telemetry/performance/PerformanceClient.ts

@@ -279,6 +279,14 @@ export abstract class PerformanceClient implements IPerformanceClient {
     protected logger: Logger;
     protected callbacks: Map<string, PerformanceCallbackFunction>;
 
+    /**
+     * Fields stamped onto every event emitted by this client (e.g. previousLibraryVersion).
+     * Unlike addFields, these are not scoped to a single correlationId and persist for the
+     * lifetime of the client. Set imperatively after construction via addGlobalFields.
+     * @protected
+     */
+    protected globalFields: { [key: string]: {} | undefined };
+
     /**
      * Multiple events with the same correlation id.
      * @protected
@@ -320,6 +328,7 @@ export abstract class PerformanceClient implements IPerformanceClient {
         this.authority = authority;
         this.libraryName = libraryName;
         this.libraryVersion = libraryVersion;
+        this.globalFields = {};
         this.applicationTelemetry = applicationTelemetry;
         this.clientId = clientId;
         this.logger = logger;
@@ -507,6 +516,12 @@ export abstract class PerformanceClient implements IPerformanceClient {
             incompleteSubsCount,
             context,
             logs: formattedLogs,
+            /*
+             * Global fields are spread last so they are always present on the
+             * emitted event and never overridden, even when registered after
+             * the measurement started.
+             */
+            ...this.globalFields,
         };
         if (account) {
             finalEvent.accountType = getAccountType(account);
@@ -568,6 +583,19 @@ export abstract class PerformanceClient implements IPerformanceClient {
         }
     }
 
+    /**
+     * Saves fields to be emitted on every event measured by this client.
+     * Unlike addFields, these are not scoped to a single correlationId and persist for the
+     * lifetime of the client (e.g. previousLibraryVersion for upgrade/downgrade telemetry).
+     * @param fields
+     */
+    addGlobalFields(fields: { [key: string]: {} | undefined }): void {
+        this.globalFields = {
+            ...this.globalFields,
+            ...fields,
+        };
+    }
+
     /**
      * Increment counters to be emitted when the measurements are flushed
      * @param fields {string[]}

package/src/telemetry/performance/StubPerformanceClient.ts

@@ -77,6 +77,10 @@ export class StubPerformanceClient implements IPerformanceClient {
         return;
     }
 
+    addGlobalFields(): void {
+        return;
+    }
+
     incrementFields(): void {
         return;
     }