@azure/msal-common 15.2.1 → 15.4.0

package/src/client/BaseClient.ts

@@ -25,7 +25,8 @@ import { version, name } from "../packageMetadata.js";
 import { CcsCredential, CcsCredentialType } from "../account/CcsCredential.js";
 import { buildClientInfoFromHomeAccountId } from "../account/ClientInfo.js";
 import { IPerformanceClient } from "../telemetry/performance/IPerformanceClient.js";
-import { RequestParameterBuilder } from "../request/RequestParameterBuilder.js";
+import * as RequestParameterBuilder from "../request/RequestParameterBuilder.js";
+import * as UrlUtils from "../utils/UrlUtils.js";
 import { BaseAuthRequest } from "../request/BaseAuthRequest.js";
 import { createDiscoveredInstance } from "../authority/AuthorityFactory.js";
 import { PerformanceEvents } from "../telemetry/performance/PerformanceEvent.js";
@@ -278,26 +279,33 @@ export abstract class BaseClient {
      * @param request
      */
     createTokenQueryParameters(request: BaseAuthRequest): string {
-        const parameterBuilder = new RequestParameterBuilder(
-            request.correlationId,
-            this.performanceClient
-        );
+        const parameters = new Map<string, string>();
 
         if (request.embeddedClientId) {
-            parameterBuilder.addBrokerParameters({
-                brokerClientId: this.config.authOptions.clientId,
-                brokerRedirectUri: this.config.authOptions.redirectUri,
-            });
+            RequestParameterBuilder.addBrokerParameters(
+                parameters,
+                this.config.authOptions.clientId,
+                this.config.authOptions.redirectUri
+            );
         }
 
         if (request.tokenQueryParameters) {
-            parameterBuilder.addExtraQueryParameters(
+            RequestParameterBuilder.addExtraQueryParameters(
+                parameters,
                 request.tokenQueryParameters
             );
         }
 
-        parameterBuilder.addCorrelationId(request.correlationId);
+        RequestParameterBuilder.addCorrelationId(
+            parameters,
+            request.correlationId
+        );
 
-        return parameterBuilder.createQueryString();
+        RequestParameterBuilder.instrumentBrokerParams(
+            parameters,
+            request.correlationId,
+            this.performanceClient
+        );
+        return UrlUtils.mapToQueryString(parameters);
     }
 }

package/src/client/RefreshTokenClient.ts

@@ -11,7 +11,8 @@ import { BaseClient } from "./BaseClient.js";
 import { CommonRefreshTokenRequest } from "../request/CommonRefreshTokenRequest.js";
 import { Authority } from "../authority/Authority.js";
 import { ServerAuthorizationTokenResponse } from "../response/ServerAuthorizationTokenResponse.js";
-import { RequestParameterBuilder } from "../request/RequestParameterBuilder.js";
+import * as RequestParameterBuilder from "../request/RequestParameterBuilder.js";
+import * as UrlUtils from "../utils/UrlUtils.js";
 import {
     GrantType,
     AuthenticationScheme,
@@ -345,46 +346,61 @@ export class RefreshTokenClient extends BaseClient {
             request.correlationId
         );
 
-        const correlationId = request.correlationId;
-        const parameterBuilder = new RequestParameterBuilder(
-            correlationId,
-            this.performanceClient
-        );
+        const parameters = new Map<string, string>();
 
-        parameterBuilder.addClientId(
+        RequestParameterBuilder.addClientId(
+            parameters,
             request.embeddedClientId ||
                 request.tokenBodyParameters?.[AADServerParamKeys.CLIENT_ID] ||
                 this.config.authOptions.clientId
         );
 
         if (request.redirectUri) {
-            parameterBuilder.addRedirectUri(request.redirectUri);
+            RequestParameterBuilder.addRedirectUri(
+                parameters,
+                request.redirectUri
+            );
         }
 
-        parameterBuilder.addScopes(
+        RequestParameterBuilder.addScopes(
+            parameters,
             request.scopes,
             true,
             this.config.authOptions.authority.options.OIDCOptions?.defaultScopes
         );
 
-        parameterBuilder.addGrantType(GrantType.REFRESH_TOKEN_GRANT);
+        RequestParameterBuilder.addGrantType(
+            parameters,
+            GrantType.REFRESH_TOKEN_GRANT
+        );
 
-        parameterBuilder.addClientInfo();
+        RequestParameterBuilder.addClientInfo(parameters);
 
-        parameterBuilder.addLibraryInfo(this.config.libraryInfo);
-        parameterBuilder.addApplicationTelemetry(
+        RequestParameterBuilder.addLibraryInfo(
+            parameters,
+            this.config.libraryInfo
+        );
+        RequestParameterBuilder.addApplicationTelemetry(
+            parameters,
             this.config.telemetry.application
         );
-        parameterBuilder.addThrottling();
+        RequestParameterBuilder.addThrottling(parameters);
 
         if (this.serverTelemetryManager && !isOidcProtocolMode(this.config)) {
-            parameterBuilder.addServerTelemetry(this.serverTelemetryManager);
+            RequestParameterBuilder.addServerTelemetry(
+                parameters,
+                this.serverTelemetryManager
+            );
         }
 
-        parameterBuilder.addRefreshToken(request.refreshToken);
+        RequestParameterBuilder.addRefreshToken(
+            parameters,
+            request.refreshToken
+        );
 
         if (this.config.clientCredentials.clientSecret) {
-            parameterBuilder.addClientSecret(
+            RequestParameterBuilder.addClientSecret(
+                parameters,
                 this.config.clientCredentials.clientSecret
             );
         }
@@ -393,14 +409,16 @@ export class RefreshTokenClient extends BaseClient {
             const clientAssertion: ClientAssertion =
                 this.config.clientCredentials.clientAssertion;
 
-            parameterBuilder.addClientAssertion(
+            RequestParameterBuilder.addClientAssertion(
+                parameters,
                 await getClientAssertion(
                     clientAssertion.assertion,
                     this.config.authOptions.clientId,
                     request.resourceRequestUri
                 )
             );
-            parameterBuilder.addClientAssertionType(
+            RequestParameterBuilder.addClientAssertionType(
+                parameters,
                 clientAssertion.assertionType
             );
         }
@@ -427,10 +445,10 @@ export class RefreshTokenClient extends BaseClient {
             }
 
             // SPA PoP requires full Base64Url encoded req_cnf string (unhashed)
-            parameterBuilder.addPopToken(reqCnfData);
+            RequestParameterBuilder.addPopToken(parameters, reqCnfData);
         } else if (request.authenticationScheme === AuthenticationScheme.SSH) {
             if (request.sshJwk) {
-                parameterBuilder.addSshJwk(request.sshJwk);
+                RequestParameterBuilder.addSshJwk(parameters, request.sshJwk);
             } else {
                 throw createClientConfigurationError(
                     ClientConfigurationErrorCodes.missingSshJwk
@@ -443,7 +461,8 @@ export class RefreshTokenClient extends BaseClient {
             (this.config.authOptions.clientCapabilities &&
                 this.config.authOptions.clientCapabilities.length > 0)
         ) {
-            parameterBuilder.addClaims(
+            RequestParameterBuilder.addClaims(
+                parameters,
                 request.claims,
                 this.config.authOptions.clientCapabilities
             );
@@ -459,7 +478,10 @@ export class RefreshTokenClient extends BaseClient {
                         const clientInfo = buildClientInfoFromHomeAccountId(
                             request.ccsCredential.credential
                         );
-                        parameterBuilder.addCcsOid(clientInfo);
+                        RequestParameterBuilder.addCcsOid(
+                            parameters,
+                            clientInfo
+                        );
                     } catch (e) {
                         this.logger.verbose(
                             "Could not parse home account ID for CCS Header: " +
@@ -468,7 +490,8 @@ export class RefreshTokenClient extends BaseClient {
                     }
                     break;
                 case CcsCredentialType.UPN:
-                    parameterBuilder.addCcsUpn(
+                    RequestParameterBuilder.addCcsUpn(
+                        parameters,
                         request.ccsCredential.credential
                     );
                     break;
@@ -476,18 +499,25 @@ export class RefreshTokenClient extends BaseClient {
         }
 
         if (request.embeddedClientId) {
-            parameterBuilder.addBrokerParameters({
-                brokerClientId: this.config.authOptions.clientId,
-                brokerRedirectUri: this.config.authOptions.redirectUri,
-            });
+            RequestParameterBuilder.addBrokerParameters(
+                parameters,
+                this.config.authOptions.clientId,
+                this.config.authOptions.redirectUri
+            );
         }
 
         if (request.tokenBodyParameters) {
-            parameterBuilder.addExtraQueryParameters(
+            RequestParameterBuilder.addExtraQueryParameters(
+                parameters,
                 request.tokenBodyParameters
             );
         }
 
-        return parameterBuilder.createQueryString();
+        RequestParameterBuilder.instrumentBrokerParams(
+            parameters,
+            request.correlationId,
+            this.performanceClient
+        );
+        return UrlUtils.mapToQueryString(parameters);
     }
 }

package/src/constants/AADServerParamKeys.ts

@@ -58,3 +58,6 @@ export const DOMAIN_HINT = "domain_hint";
 export const X_CLIENT_EXTRA_SKU = "x-client-xtra-sku";
 export const BROKER_CLIENT_ID = "brk_client_id";
 export const BROKER_REDIRECT_URI = "brk_redirect_uri";
+export const INSTANCE_AWARE = "instance_aware";
+export const EAR_JWK = "ear_jwk";
+export const EAR_JWE_CRYPTO = "ear_jwe_crypto";

package/src/exports-common.ts

@@ -105,19 +105,21 @@ export {
     DEFAULT_CRYPTO_IMPLEMENTATION,
     SignedHttpRequestParameters,
 } from "./crypto/ICrypto.js";
+
+export * as AuthorizeProtocol from "./protocol/Authorize.js";
 export { BaseAuthRequest } from "./request/BaseAuthRequest.js";
 export { CommonAuthorizationUrlRequest } from "./request/CommonAuthorizationUrlRequest.js";
 export { CommonAuthorizationCodeRequest } from "./request/CommonAuthorizationCodeRequest.js";
 export { CommonRefreshTokenRequest } from "./request/CommonRefreshTokenRequest.js";
 export { CommonSilentFlowRequest } from "./request/CommonSilentFlowRequest.js";
 export { CommonEndSessionRequest } from "./request/CommonEndSessionRequest.js";
-export { RequestParameterBuilder } from "./request/RequestParameterBuilder.js";
+export * as RequestParameterBuilder from "./request/RequestParameterBuilder.js";
 export { StoreInCache } from "./request/StoreInCache.js";
 export { AzureRegion } from "./authority/AzureRegion.js";
 export { AzureRegionConfiguration } from "./authority/AzureRegionConfiguration.js";
 export { AuthenticationResult } from "./response/AuthenticationResult.js";
 export { AuthorizationCodePayload } from "./response/AuthorizationCodePayload.js";
-export { ServerAuthorizationCodeResponse } from "./response/ServerAuthorizationCodeResponse.js";
+export { AuthorizeResponse } from "./response/AuthorizeResponse.js";
 export { ServerAuthorizationTokenResponse } from "./response/ServerAuthorizationTokenResponse.js";
 export {
     ResponseHandler,
@@ -158,6 +160,7 @@ export {
     OIDC_DEFAULT_SCOPES,
     PromptValue,
     PersistentCacheKeys,
+    OAuthResponseType,
     ServerResponseType,
     ResponseMode,
     CacheOutcome,

package/src/packageMetadata.ts

@@ -1,3 +1,3 @@
 /* eslint-disable header/header */
 export const name = "@azure/msal-common";
-export const version = "15.2.1";
+export const version = "15.4.0";

package/src/protocol/Authorize.ts

@@ -0,0 +1,409 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CommonAuthorizationUrlRequest } from "../request/CommonAuthorizationUrlRequest.js";
+import * as RequestParameterBuilder from "../request/RequestParameterBuilder.js";
+import { IPerformanceClient } from "../telemetry/performance/IPerformanceClient.js";
+import * as AADServerParamKeys from "../constants/AADServerParamKeys.js";
+import { AuthOptions } from "../config/ClientConfiguration.js";
+import { PromptValue } from "../utils/Constants.js";
+import { AccountInfo } from "../account/AccountInfo.js";
+import { Logger } from "../logger/Logger.js";
+import { buildClientInfoFromHomeAccountId } from "../account/ClientInfo.js";
+import { Authority } from "../authority/Authority.js";
+import { mapToQueryString } from "../utils/UrlUtils.js";
+import { UrlString } from "../url/UrlString.js";
+import { AuthorizationCodePayload } from "../response/AuthorizationCodePayload.js";
+import { AuthorizeResponse } from "../response/AuthorizeResponse.js";
+import {
+    ClientAuthErrorCodes,
+    createClientAuthError,
+} from "../error/ClientAuthError.js";
+import {
+    InteractionRequiredAuthError,
+    isInteractionRequiredError,
+} from "../error/InteractionRequiredAuthError.js";
+import { ServerError } from "../error/ServerError.js";
+
+/**
+ * Returns map of parameters that are applicable to all calls to /authorize whether using PKCE or EAR
+ * @param config
+ * @param request
+ * @param logger
+ * @param performanceClient
+ * @returns
+ */
+export function getStandardAuthorizeRequestParameters(
+    authOptions: AuthOptions,
+    request: CommonAuthorizationUrlRequest,
+    logger: Logger,
+    performanceClient?: IPerformanceClient
+): Map<string, string> {
+    // generate the correlationId if not set by the user and add
+    const correlationId = request.correlationId;
+
+    const parameters = new Map<string, string>();
+
+    RequestParameterBuilder.addClientId(
+        parameters,
+        request.embeddedClientId ||
+            request.extraQueryParameters?.[AADServerParamKeys.CLIENT_ID] ||
+            authOptions.clientId
+    );
+
+    const requestScopes = [
+        ...(request.scopes || []),
+        ...(request.extraScopesToConsent || []),
+    ];
+    RequestParameterBuilder.addScopes(
+        parameters,
+        requestScopes,
+        true,
+        authOptions.authority.options.OIDCOptions?.defaultScopes
+    );
+
+    RequestParameterBuilder.addRedirectUri(parameters, request.redirectUri);
+
+    RequestParameterBuilder.addCorrelationId(parameters, correlationId);
+
+    // add response_mode. If not passed in it defaults to query.
+    RequestParameterBuilder.addResponseMode(parameters, request.responseMode);
+
+    // add client_info=1
+    RequestParameterBuilder.addClientInfo(parameters);
+
+    if (request.prompt) {
+        RequestParameterBuilder.addPrompt(parameters, request.prompt);
+        performanceClient?.addFields({ prompt: request.prompt }, correlationId);
+    }
+
+    if (request.domainHint) {
+        RequestParameterBuilder.addDomainHint(parameters, request.domainHint);
+        performanceClient?.addFields(
+            { domainHintFromRequest: true },
+            correlationId
+        );
+    }
+
+    // Add sid or loginHint with preference for login_hint claim (in request) -> sid -> loginHint (upn/email) -> username of AccountInfo object
+    if (request.prompt !== PromptValue.SELECT_ACCOUNT) {
+        // AAD will throw if prompt=select_account is passed with an account hint
+        if (request.sid && request.prompt === PromptValue.NONE) {
+            // SessionID is only used in silent calls
+            logger.verbose(
+                "createAuthCodeUrlQueryString: Prompt is none, adding sid from request"
+            );
+            RequestParameterBuilder.addSid(parameters, request.sid);
+            performanceClient?.addFields(
+                { sidFromRequest: true },
+                correlationId
+            );
+        } else if (request.account) {
+            const accountSid = extractAccountSid(request.account);
+            let accountLoginHintClaim = extractLoginHint(request.account);
+
+            if (accountLoginHintClaim && request.domainHint) {
+                logger.warning(
+                    `AuthorizationCodeClient.createAuthCodeUrlQueryString: "domainHint" param is set, skipping opaque "login_hint" claim. Please consider not passing domainHint`
+                );
+                accountLoginHintClaim = null;
+            }
+
+            // If login_hint claim is present, use it over sid/username
+            if (accountLoginHintClaim) {
+                logger.verbose(
+                    "createAuthCodeUrlQueryString: login_hint claim present on account"
+                );
+                RequestParameterBuilder.addLoginHint(
+                    parameters,
+                    accountLoginHintClaim
+                );
+                performanceClient?.addFields(
+                    { loginHintFromClaim: true },
+                    correlationId
+                );
+                try {
+                    const clientInfo = buildClientInfoFromHomeAccountId(
+                        request.account.homeAccountId
+                    );
+                    RequestParameterBuilder.addCcsOid(parameters, clientInfo);
+                } catch (e) {
+                    logger.verbose(
+                        "createAuthCodeUrlQueryString: Could not parse home account ID for CCS Header"
+                    );
+                }
+            } else if (accountSid && request.prompt === PromptValue.NONE) {
+                /*
+                 * If account and loginHint are provided, we will check account first for sid before adding loginHint
+                 * SessionId is only used in silent calls
+                 */
+                logger.verbose(
+                    "createAuthCodeUrlQueryString: Prompt is none, adding sid from account"
+                );
+                RequestParameterBuilder.addSid(parameters, accountSid);
+                performanceClient?.addFields(
+                    { sidFromClaim: true },
+                    correlationId
+                );
+                try {
+                    const clientInfo = buildClientInfoFromHomeAccountId(
+                        request.account.homeAccountId
+                    );
+                    RequestParameterBuilder.addCcsOid(parameters, clientInfo);
+                } catch (e) {
+                    logger.verbose(
+                        "createAuthCodeUrlQueryString: Could not parse home account ID for CCS Header"
+                    );
+                }
+            } else if (request.loginHint) {
+                logger.verbose(
+                    "createAuthCodeUrlQueryString: Adding login_hint from request"
+                );
+                RequestParameterBuilder.addLoginHint(
+                    parameters,
+                    request.loginHint
+                );
+                RequestParameterBuilder.addCcsUpn(
+                    parameters,
+                    request.loginHint
+                );
+                performanceClient?.addFields(
+                    { loginHintFromRequest: true },
+                    correlationId
+                );
+            } else if (request.account.username) {
+                // Fallback to account username if provided
+                logger.verbose(
+                    "createAuthCodeUrlQueryString: Adding login_hint from account"
+                );
+                RequestParameterBuilder.addLoginHint(
+                    parameters,
+                    request.account.username
+                );
+                performanceClient?.addFields(
+                    { loginHintFromUpn: true },
+                    correlationId
+                );
+                try {
+                    const clientInfo = buildClientInfoFromHomeAccountId(
+                        request.account.homeAccountId
+                    );
+                    RequestParameterBuilder.addCcsOid(parameters, clientInfo);
+                } catch (e) {
+                    logger.verbose(
+                        "createAuthCodeUrlQueryString: Could not parse home account ID for CCS Header"
+                    );
+                }
+            }
+        } else if (request.loginHint) {
+            logger.verbose(
+                "createAuthCodeUrlQueryString: No account, adding login_hint from request"
+            );
+            RequestParameterBuilder.addLoginHint(parameters, request.loginHint);
+            RequestParameterBuilder.addCcsUpn(parameters, request.loginHint);
+            performanceClient?.addFields(
+                { loginHintFromRequest: true },
+                correlationId
+            );
+        }
+    } else {
+        logger.verbose(
+            "createAuthCodeUrlQueryString: Prompt is select_account, ignoring account hints"
+        );
+    }
+
+    if (request.nonce) {
+        RequestParameterBuilder.addNonce(parameters, request.nonce);
+    }
+
+    if (request.state) {
+        RequestParameterBuilder.addState(parameters, request.state);
+    }
+
+    if (
+        request.claims ||
+        (authOptions.clientCapabilities &&
+            authOptions.clientCapabilities.length > 0)
+    ) {
+        RequestParameterBuilder.addClaims(
+            parameters,
+            request.claims,
+            authOptions.clientCapabilities
+        );
+    }
+
+    if (request.embeddedClientId) {
+        RequestParameterBuilder.addBrokerParameters(
+            parameters,
+            authOptions.clientId,
+            authOptions.redirectUri
+        );
+    }
+
+    // If extraQueryParameters includes instance_aware its value will be added when extraQueryParameters are added
+    if (
+        authOptions.instanceAware &&
+        (!request.extraQueryParameters ||
+            !Object.keys(request.extraQueryParameters).includes(
+                AADServerParamKeys.INSTANCE_AWARE
+            ))
+    ) {
+        RequestParameterBuilder.addInstanceAware(parameters);
+    }
+
+    return parameters;
+}
+
+/**
+ * Returns authorize endpoint with given request parameters in the query string
+ * @param authority
+ * @param requestParameters
+ * @returns
+ */
+export function getAuthorizeUrl(
+    authority: Authority,
+    requestParameters: Map<string, string>
+): string {
+    const queryString = mapToQueryString(requestParameters);
+
+    return UrlString.appendQueryString(
+        authority.authorizationEndpoint,
+        queryString
+    );
+}
+
+/**
+ * Handles the hash fragment response from public client code request. Returns a code response used by
+ * the client to exchange for a token in acquireToken.
+ * @param serverParams
+ * @param cachedState
+ */
+export function getAuthorizationCodePayload(
+    serverParams: AuthorizeResponse,
+    cachedState: string
+): AuthorizationCodePayload {
+    // Get code response
+    validateAuthorizationResponse(serverParams, cachedState);
+
+    // throw when there is no auth code in the response
+    if (!serverParams.code) {
+        throw createClientAuthError(
+            ClientAuthErrorCodes.authorizationCodeMissingFromServerResponse
+        );
+    }
+
+    return serverParams as AuthorizationCodePayload;
+}
+
+/**
+ * Function which validates server authorization code response.
+ * @param serverResponseHash
+ * @param requestState
+ */
+export function validateAuthorizationResponse(
+    serverResponse: AuthorizeResponse,
+    requestState: string
+): void {
+    if (!serverResponse.state || !requestState) {
+        throw serverResponse.state
+            ? createClientAuthError(
+                  ClientAuthErrorCodes.stateNotFound,
+                  "Cached State"
+              )
+            : createClientAuthError(
+                  ClientAuthErrorCodes.stateNotFound,
+                  "Server State"
+              );
+    }
+
+    let decodedServerResponseState: string;
+    let decodedRequestState: string;
+
+    try {
+        decodedServerResponseState = decodeURIComponent(serverResponse.state);
+    } catch (e) {
+        throw createClientAuthError(
+            ClientAuthErrorCodes.invalidState,
+            serverResponse.state
+        );
+    }
+
+    try {
+        decodedRequestState = decodeURIComponent(requestState);
+    } catch (e) {
+        throw createClientAuthError(
+            ClientAuthErrorCodes.invalidState,
+            serverResponse.state
+        );
+    }
+
+    if (decodedServerResponseState !== decodedRequestState) {
+        throw createClientAuthError(ClientAuthErrorCodes.stateMismatch);
+    }
+
+    // Check for error
+    if (
+        serverResponse.error ||
+        serverResponse.error_description ||
+        serverResponse.suberror
+    ) {
+        const serverErrorNo = parseServerErrorNo(serverResponse);
+        if (
+            isInteractionRequiredError(
+                serverResponse.error,
+                serverResponse.error_description,
+                serverResponse.suberror
+            )
+        ) {
+            throw new InteractionRequiredAuthError(
+                serverResponse.error || "",
+                serverResponse.error_description,
+                serverResponse.suberror,
+                serverResponse.timestamp || "",
+                serverResponse.trace_id || "",
+                serverResponse.correlation_id || "",
+                serverResponse.claims || "",
+                serverErrorNo
+            );
+        }
+
+        throw new ServerError(
+            serverResponse.error || "",
+            serverResponse.error_description,
+            serverResponse.suberror,
+            serverErrorNo
+        );
+    }
+}
+
+/**
+ * Get server error No from the error_uri
+ * @param serverResponse
+ * @returns
+ */
+function parseServerErrorNo(
+    serverResponse: AuthorizeResponse
+): string | undefined {
+    const errorCodePrefix = "code=";
+    const errorCodePrefixIndex =
+        serverResponse.error_uri?.lastIndexOf(errorCodePrefix);
+    return errorCodePrefixIndex && errorCodePrefixIndex >= 0
+        ? serverResponse.error_uri?.substring(
+              errorCodePrefixIndex + errorCodePrefix.length
+          )
+        : undefined;
+}
+
+/**
+ * Helper to get sid from account. Returns null if idTokenClaims are not present or sid is not present.
+ * @param account
+ */
+function extractAccountSid(account: AccountInfo): string | null {
+    return account.idTokenClaims?.sid || null;
+}
+
+function extractLoginHint(account: AccountInfo): string | null {
+    return account.idTokenClaims?.login_hint || null;
+}