@azure/msal-common 16.8.0 → 16.10.0

package/src/protocol/Authorize.ts

@@ -34,6 +34,7 @@ import { ServerError } from "../error/ServerError.js";
  * @param logger
  * @param performanceClient
  * @returns
+ * @internal
  */
 export function getStandardAuthorizeRequestParameters(
     authOptions: AuthOptions,
@@ -60,6 +61,7 @@ export function getStandardAuthorizeRequestParameters(
     RequestParameterBuilder.addScopes(
         parameters,
         requestScopes,
+        request.correlationId,
         true,
         authOptions.authority.options.OIDCOptions?.defaultScopes
     );
@@ -248,6 +250,7 @@ export function getStandardAuthorizeRequestParameters(
 
     RequestParameterBuilder.addClaims(
         parameters,
+        request.correlationId,
         request.claims,
         authOptions.clientCapabilities,
         request.skipBrokerClaims
@@ -272,6 +275,7 @@ export function getStandardAuthorizeRequestParameters(
  * @param authority
  * @param requestParameters
  * @returns
+ * @internal
  */
 export function getAuthorizeUrl(
     authority: Authority,
@@ -289,18 +293,21 @@ export function getAuthorizeUrl(
  * the client to exchange for a token in acquireToken.
  * @param serverParams
  * @param cachedState
+ * @param correlationId
  */
 export function getAuthorizationCodePayload(
     serverParams: AuthorizeResponse,
-    cachedState: string
+    cachedState: string,
+    correlationId: string
 ): AuthorizationCodePayload {
     // Get code response
-    validateAuthorizationResponse(serverParams, cachedState);
+    validateAuthorizationResponse(serverParams, cachedState, correlationId);
 
     // throw when there is no auth code in the response
     if (!serverParams.code) {
         throw createClientAuthError(
-            ClientAuthErrorCodes.authorizationCodeMissingFromServerResponse
+            ClientAuthErrorCodes.authorizationCodeMissingFromServerResponse,
+            correlationId
         );
     }
 
@@ -311,19 +318,23 @@ export function getAuthorizationCodePayload(
  * Function which validates server authorization code response.
  * @param serverResponseHash
  * @param requestState
+ * @param correlationId
  */
 export function validateAuthorizationResponse(
     serverResponse: AuthorizeResponse,
-    requestState: string
+    requestState: string,
+    correlationId: string
 ): void {
     if (!serverResponse.state || !requestState) {
         throw serverResponse.state
             ? createClientAuthError(
                   ClientAuthErrorCodes.stateNotFound,
+                  correlationId,
                   "Cached State"
               )
             : createClientAuthError(
                   ClientAuthErrorCodes.stateNotFound,
+                  correlationId,
                   "Server State"
               );
     }
@@ -336,6 +347,7 @@ export function validateAuthorizationResponse(
     } catch (e) {
         throw createClientAuthError(
             ClientAuthErrorCodes.invalidState,
+            correlationId,
             serverResponse.state
         );
     }
@@ -345,12 +357,16 @@ export function validateAuthorizationResponse(
     } catch (e) {
         throw createClientAuthError(
             ClientAuthErrorCodes.invalidState,
+            correlationId,
             serverResponse.state
         );
     }
 
     if (decodedServerResponseState !== decodedRequestState) {
-        throw createClientAuthError(ClientAuthErrorCodes.stateMismatch);
+        throw createClientAuthError(
+            ClientAuthErrorCodes.stateMismatch,
+            correlationId
+        );
     }
 
     // Check for error
@@ -369,11 +385,11 @@ export function validateAuthorizationResponse(
         ) {
             throw new InteractionRequiredAuthError(
                 serverResponse.error || "",
+                serverResponse.correlation_id || correlationId,
                 serverResponse.error_description,
                 serverResponse.suberror,
                 serverResponse.timestamp || "",
                 serverResponse.trace_id || "",
-                serverResponse.correlation_id || "",
                 serverResponse.claims || "",
                 serverErrorNo
             );
@@ -381,6 +397,7 @@ export function validateAuthorizationResponse(
 
         throw new ServerError(
             serverResponse.error || "",
+            serverResponse.correlation_id || correlationId,
             serverResponse.error_description,
             serverResponse.suberror,
             serverErrorNo

package/src/protocol/Token.ts

@@ -108,6 +108,7 @@ export function createTokenQueryParameters(
  * @param queryString
  * @param headers
  * @param thumbprint
+ * @internal
  */
 export async function executePostToTokenEndpoint(
     tokenEndpoint: string,
@@ -154,6 +155,7 @@ export async function executePostToTokenEndpoint(
  * @param networkClient - Network module instance
  * @param logger - Logger instance
  * @param performanceClient - Performance client instance
+ * @internal
  */
 export async function sendPostRequest<
     T extends ServerAuthorizationTokenResponse
@@ -215,7 +217,10 @@ export async function sendPostRequest<
         if (e instanceof AuthError) {
             throw e;
         } else {
-            throw createClientAuthError(ClientAuthErrorCodes.networkError);
+            throw createClientAuthError(
+                ClientAuthErrorCodes.networkError,
+                correlationId
+            );
         }
     }
 

package/src/request/AuthenticationHeaderParser.ts

@@ -44,7 +44,8 @@ export class AuthenticationHeaderParser {
                 return authenticationInfoChallenges.nextnonce;
             }
             throw createClientConfigurationError(
-                ClientConfigurationErrorCodes.invalidAuthenticationHeader
+                ClientConfigurationErrorCodes.invalidAuthenticationHeader,
+                ""
             );
         }
 
@@ -59,13 +60,15 @@ export class AuthenticationHeaderParser {
                 return wwwAuthenticateChallenges.nonce;
             }
             throw createClientConfigurationError(
-                ClientConfigurationErrorCodes.invalidAuthenticationHeader
+                ClientConfigurationErrorCodes.invalidAuthenticationHeader,
+                ""
             );
         }
 
         // If neither header is present, throw missing headers error
         throw createClientConfigurationError(
-            ClientConfigurationErrorCodes.missingNonceAuthenticationHeader
+            ClientConfigurationErrorCodes.missingNonceAuthenticationHeader,
+            ""
         );
     }
 

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
             )
         ) {
@@ -591,29 +624,20 @@ export function addSshJwk(
 /**
  * add server telemetry fields
  * @param serverTelemetryManager
+ * @internal
  */
 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;
+};