@azure/msal-browser 4.22.1 → 4.24.0

package/src/custom_auth/core/auth_flow/mfa/state/MfaState.ts

@@ -0,0 +1,188 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    MfaAwaitingStateParameters,
+    MfaStateParameters,
+    MfaVerificationRequiredStateParameters,
+} from "./MfaStateParameters.js";
+import { MfaSubmitChallengeResult } from "../result/MfaSubmitChallengeResult.js";
+import { MfaRequestChallengeResult } from "../result/MfaRequestChallengeResult.js";
+import {
+    MfaSubmitChallengeParams,
+    MfaRequestChallengeParams,
+} from "../../../interaction_client/mfa/parameter/MfaClientParameters.js";
+import { CustomAuthAccountData } from "../../../../get_account/auth_flow/CustomAuthAccountData.js";
+import { MfaCompletedState } from "./MfaCompletedState.js";
+import { ensureArgumentIsNotEmptyString } from "../../../utils/ArgumentValidator.js";
+import { AuthenticationMethod } from "../../../network_client/custom_auth_api/types/ApiResponseTypes.js";
+import { AuthFlowActionRequiredStateBase } from "../../AuthFlowState.js";
+
+abstract class MfaState<
+    TParameters extends MfaStateParameters
+> extends AuthFlowActionRequiredStateBase<TParameters> {
+    /**
+     * Requests an MFA challenge for a specific authentication method.
+     * @param authMethodId The authentication method ID to use for the challenge.
+     * @returns Promise that resolves to MfaRequestChallengeResult.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    async requestChallenge(
+        authMethodId: string
+    ): Promise<MfaRequestChallengeResult> {
+        try {
+            ensureArgumentIsNotEmptyString("authMethodId", authMethodId);
+
+            this.stateParameters.logger.verbose(
+                `Requesting MFA challenge with authentication method - '${authMethodId}'.`,
+                this.stateParameters.correlationId
+            );
+
+            const requestParams: MfaRequestChallengeParams = {
+                correlationId: this.stateParameters.correlationId,
+                continuationToken: this.stateParameters.continuationToken ?? "",
+                challengeType:
+                    this.stateParameters.config.customAuth.challengeTypes ?? [],
+                authMethodId: authMethodId,
+            };
+
+            const result =
+                await this.stateParameters.mfaClient.requestChallenge(
+                    requestParams
+                );
+
+            this.stateParameters.logger.verbose(
+                "MFA challenge requested successfully.",
+                this.stateParameters.correlationId
+            );
+
+            return new MfaRequestChallengeResult(
+                new MfaVerificationRequiredState({
+                    correlationId: result.correlationId,
+                    continuationToken: result.continuationToken,
+                    config: this.stateParameters.config,
+                    logger: this.stateParameters.logger,
+                    mfaClient: this.stateParameters.mfaClient,
+                    cacheClient: this.stateParameters.cacheClient,
+                    challengeChannel: result.challengeChannel,
+                    challengeTargetLabel: result.challengeTargetLabel,
+                    codeLength: result.codeLength,
+                    selectedAuthMethodId: authMethodId,
+                    scopes: this.stateParameters.scopes ?? [],
+                })
+            );
+        } catch (error) {
+            this.stateParameters.logger.errorPii(
+                `Failed to request MFA challenge. Error: ${error}.`,
+                this.stateParameters.correlationId
+            );
+
+            return MfaRequestChallengeResult.createWithError(error);
+        }
+    }
+}
+
+/**
+ * State indicating that MFA is required and awaiting user action.
+ * This state allows the developer to pause execution before sending the code to the user's email.
+ */
+export class MfaAwaitingState extends MfaState<MfaAwaitingStateParameters> {
+    /**
+     * Gets the available authentication methods for MFA.
+     * @returns Array of available authentication methods.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    getAuthMethods(): AuthenticationMethod[] {
+        return this.stateParameters.authMethods;
+    }
+}
+
+/**
+ * State indicating that MFA verification is required.
+ * The challenge has been sent and the user needs to provide the code.
+ */
+export class MfaVerificationRequiredState extends MfaState<MfaVerificationRequiredStateParameters> {
+    /**
+     * Gets the length of the code that the user needs to provide.
+     * @returns The expected code length.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    getCodeLength(): number {
+        return this.stateParameters.codeLength;
+    }
+
+    /**
+     * Gets the channel through which the challenge was sent.
+     * @returns The challenge channel (e.g., "email").
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    getChannel(): string {
+        return this.stateParameters.challengeChannel;
+    }
+
+    /**
+     * Gets the target label indicating where the challenge was sent.
+     * @returns The challenge target label (e.g., masked email address).
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    getSentTo(): string {
+        return this.stateParameters.challengeTargetLabel;
+    }
+
+    /**
+     * Submits the MFA challenge (e.g., OTP code) to complete the authentication.
+     * @param challenge The challenge code (e.g., OTP code) entered by the user.
+     * @returns Promise that resolves to MfaSubmitChallengeResult.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    async submitChallenge(
+        challenge: string
+    ): Promise<MfaSubmitChallengeResult> {
+        try {
+            this.ensureCodeIsValid(challenge, this.getCodeLength());
+
+            this.stateParameters.logger.verbose(
+                "Submitting MFA challenge.",
+                this.stateParameters.correlationId
+            );
+
+            const submitParams: MfaSubmitChallengeParams = {
+                correlationId: this.stateParameters.correlationId,
+                continuationToken: this.stateParameters.continuationToken ?? "",
+                scopes: this.stateParameters.scopes ?? [],
+                challenge: challenge,
+            };
+
+            const result = await this.stateParameters.mfaClient.submitChallenge(
+                submitParams
+            );
+
+            this.stateParameters.logger.verbose(
+                "MFA challenge submitted successfully.",
+                this.stateParameters.correlationId
+            );
+
+            const accountInfo = new CustomAuthAccountData(
+                result.authenticationResult.account,
+                this.stateParameters.config,
+                this.stateParameters.cacheClient,
+                this.stateParameters.logger,
+                this.stateParameters.correlationId
+            );
+
+            return new MfaSubmitChallengeResult(
+                new MfaCompletedState(),
+                accountInfo
+            );
+        } catch (error) {
+            this.stateParameters.logger.errorPii(
+                `Failed to submit MFA challenge. Error: ${error}.`,
+                this.stateParameters.correlationId
+            );
+
+            return MfaSubmitChallengeResult.createWithError(error);
+        }
+    }
+}

package/src/custom_auth/core/auth_flow/mfa/state/MfaStateParameters.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowActionRequiredStateParameters } from "../../AuthFlowState.js";
+import { MfaClient } from "../../../interaction_client/mfa/MfaClient.js";
+import { AuthenticationMethod } from "../../../network_client/custom_auth_api/types/ApiResponseTypes.js";
+import { CustomAuthSilentCacheClient } from "../../../../get_account/interaction_client/CustomAuthSilentCacheClient.js";
+
+export interface MfaStateParameters
+    extends AuthFlowActionRequiredStateParameters {
+    mfaClient: MfaClient;
+    cacheClient: CustomAuthSilentCacheClient;
+    scopes?: string[];
+}
+
+export interface MfaVerificationRequiredStateParameters
+    extends MfaStateParameters {
+    challengeChannel: string;
+    challengeTargetLabel: string;
+    codeLength: number;
+    selectedAuthMethodId?: string;
+}
+
+export interface MfaAwaitingStateParameters extends MfaStateParameters {
+    authMethods: AuthenticationMethod[];
+}

package/src/custom_auth/core/error/MsalCustomAuthError.ts

@@ -6,17 +6,14 @@
 import { CustomAuthError } from "./CustomAuthError.js";
 
 export class MsalCustomAuthError extends CustomAuthError {
-    subError: string | undefined;
-
     constructor(
         error: string,
         errorDescription?: string,
         subError?: string,
+        errorCodes?: Array<number>,
         correlationId?: string
     ) {
-        super(error, errorDescription, correlationId);
+        super(error, errorDescription, correlationId, errorCodes, subError);
         Object.setPrototypeOf(this, MsalCustomAuthError.prototype);
-
-        this.subError = subError || "";
     }
 }

package/src/custom_auth/core/interaction_client/CustomAuthInteractionClientBase.ts

@@ -15,6 +15,7 @@ import {
     ICrypto,
     IPerformanceClient,
     Logger,
+    ResponseHandler,
 } from "@azure/msal-common/browser";
 import { EventHandler } from "../../../event/EventHandler.js";
 import { INavigationClient } from "../../../navigation/INavigationClient.js";
@@ -24,8 +25,11 @@ import { SsoSilentRequest } from "../../../request/SsoSilentRequest.js";
 import { EndSessionRequest } from "../../../request/EndSessionRequest.js";
 import { ClearCacheRequest } from "../../../request/ClearCacheRequest.js";
 import { AuthenticationResult } from "../../../response/AuthenticationResult.js";
+import { SignInTokenResponse } from "../network_client/custom_auth_api/types/ApiResponseTypes.js";
 
 export abstract class CustomAuthInteractionClientBase extends StandardInteractionClient {
+    private readonly tokenResponseHandler: ResponseHandler;
+
     constructor(
         config: BrowserConfiguration,
         storageImpl: BrowserCacheManager,
@@ -46,6 +50,15 @@ export abstract class CustomAuthInteractionClientBase extends StandardInteractio
             navigationClient,
             performanceClient
         );
+
+        this.tokenResponseHandler = new ResponseHandler(
+            this.config.auth.clientId,
+            this.browserStorage,
+            this.browserCrypto,
+            this.logger,
+            null,
+            null
+        );
     }
 
     protected getChallengeTypes(
@@ -74,6 +87,39 @@ export abstract class CustomAuthInteractionClientBase extends StandardInteractio
         ];
     }
 
+    /**
+     * Common method to handle token response processing.
+     * @param tokenResponse The token response from the API
+     * @param requestScopes Scopes for the token request
+     * @param correlationId Correlation ID for logging
+     * @returns Authentication result from the token response
+     */
+    protected async handleTokenResponse(
+        tokenResponse: SignInTokenResponse,
+        requestScopes: string[],
+        correlationId: string
+    ): Promise<AuthenticationResult> {
+        this.logger.verbose("Processing token response.", correlationId);
+
+        const requestTimestamp = Math.round(new Date().getTime() / 1000.0);
+
+        // Save tokens and create authentication result
+        const result =
+            await this.tokenResponseHandler.handleServerTokenResponse(
+                tokenResponse,
+                this.customAuthAuthority,
+                requestTimestamp,
+                {
+                    authority: this.customAuthAuthority.canonicalAuthority,
+                    correlationId:
+                        tokenResponse.correlation_id ?? correlationId,
+                    scopes: requestScopes,
+                }
+            );
+
+        return result as AuthenticationResult;
+    }
+
     // It is not necessary to implement this method from base class.
     acquireToken(
         // eslint-disable-next-line @typescript-eslint/no-unused-vars

package/src/custom_auth/core/interaction_client/jit/JitClient.ts

@@ -0,0 +1,165 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CustomAuthInteractionClientBase } from "../CustomAuthInteractionClientBase.js";
+import {
+    JitChallengeAuthMethodParams,
+    JitSubmitChallengeParams,
+} from "./parameter/JitParams.js";
+import {
+    JitVerificationRequiredResult,
+    JitCompletedResult,
+    createJitVerificationRequiredResult,
+    createJitCompletedResult,
+} from "./result/JitActionResult.js";
+import {
+    DefaultCustomAuthApiCodeLength,
+    ChallengeType,
+    GrantType,
+} from "../../../CustomAuthConstants.js";
+import * as PublicApiId from "../../telemetry/PublicApiId.js";
+import {
+    RegisterChallengeRequest,
+    RegisterContinueRequest,
+    SignInContinuationTokenRequest,
+} from "../../network_client/custom_auth_api/types/ApiRequestTypes.js";
+
+/**
+ * JIT client for handling just-in-time authentication method registration flows.
+ */
+export class JitClient extends CustomAuthInteractionClientBase {
+    /**
+     * Challenges an authentication method for JIT registration.
+     * @param parameters The parameters for challenging the auth method.
+     * @returns Promise that resolves to either JitVerificationRequiredResult or JitCompletedResult.
+     */
+    async challengeAuthMethod(
+        parameters: JitChallengeAuthMethodParams
+    ): Promise<JitVerificationRequiredResult | JitCompletedResult> {
+        const apiId = PublicApiId.JIT_CHALLENGE_AUTH_METHOD;
+        const telemetryManager = this.initializeServerTelemetryManager(apiId);
+
+        this.logger.verbose(
+            "Calling challenge endpoint for getting auth method.",
+            parameters.correlationId
+        );
+
+        const challengeReq: RegisterChallengeRequest = {
+            continuation_token: parameters.continuationToken,
+            challenge_type: parameters.authMethod.challenge_type,
+            challenge_target: parameters.verificationContact,
+            challenge_channel: parameters.authMethod.challenge_channel,
+            correlationId: parameters.correlationId,
+            telemetryManager: telemetryManager,
+        };
+
+        const challengeResponse =
+            await this.customAuthApiClient.registerApi.challenge(challengeReq);
+
+        this.logger.verbose(
+            "Challenge endpoint called for auth method registration.",
+            parameters.correlationId
+        );
+
+        /*
+         * Handle fast-pass scenario (preverified)
+         * This occurs when the user selects the same email used during sign-up
+         * Since the email was already verified during sign-up, no additional verification is needed
+         */
+        if (challengeResponse.challenge_type === ChallengeType.PREVERIFIED) {
+            this.logger.verbose(
+                "Fast-pass scenario detected - completing registration without additional verification.",
+                challengeResponse.correlation_id
+            );
+
+            // Use submitChallenge for fast-pass scenario with continuation_token grant type
+            const fastPassParams: JitSubmitChallengeParams = {
+                correlationId: challengeResponse.correlation_id,
+                continuationToken: challengeResponse.continuation_token,
+                grantType: GrantType.CONTINUATION_TOKEN,
+                scopes: parameters.scopes,
+                username: parameters.username,
+                claims: parameters.claims,
+            };
+
+            const completedResult = await this.submitChallenge(fastPassParams);
+            return completedResult;
+        }
+
+        // Verification required
+        return createJitVerificationRequiredResult({
+            correlationId: challengeResponse.correlation_id,
+            continuationToken: challengeResponse.continuation_token,
+            challengeChannel: challengeResponse.challenge_channel,
+            challengeTargetLabel: challengeResponse.challenge_target,
+            codeLength:
+                challengeResponse.code_length || DefaultCustomAuthApiCodeLength,
+        });
+    }
+
+    /**
+     * Submits challenge response and completes JIT registration.
+     * @param parameters The parameters for submitting the challenge.
+     * @returns Promise that resolves to JitCompletedResult.
+     */
+    async submitChallenge(
+        parameters: JitSubmitChallengeParams
+    ): Promise<JitCompletedResult> {
+        const apiId = PublicApiId.JIT_SUBMIT_CHALLENGE;
+        const telemetryManager = this.initializeServerTelemetryManager(apiId);
+
+        this.logger.verbose(
+            "Calling continue endpoint for auth method challenge submission.",
+            parameters.correlationId
+        );
+
+        // Submit challenge to complete registration
+        const continueReq: RegisterContinueRequest = {
+            continuation_token: parameters.continuationToken,
+            grant_type: parameters.grantType,
+            ...(parameters.challenge && {
+                oob: parameters.challenge,
+            }),
+            correlationId: parameters.correlationId,
+            telemetryManager: telemetryManager,
+        };
+
+        const continueResponse =
+            await this.customAuthApiClient.registerApi.continue(continueReq);
+
+        this.logger.verbose(
+            "Continue endpoint called for auth method challenge submission.",
+            parameters.correlationId
+        );
+
+        // Use continuation token to get authentication tokens
+        const scopes = this.getScopes(parameters.scopes);
+        const tokenRequest: SignInContinuationTokenRequest = {
+            continuation_token: continueResponse.continuation_token,
+            scope: scopes.join(" "),
+            correlationId: continueResponse.correlation_id,
+            telemetryManager: telemetryManager,
+            ...(parameters.claims && {
+                claims: parameters.claims,
+            }),
+        };
+
+        const tokenResponse =
+            await this.customAuthApiClient.signInApi.requestTokenWithContinuationToken(
+                tokenRequest
+            );
+
+        const authResult = await this.handleTokenResponse(
+            tokenResponse,
+            scopes,
+            tokenResponse.correlation_id || continueResponse.correlation_id
+        );
+
+        return createJitCompletedResult({
+            correlationId: continueResponse.correlation_id,
+            authenticationResult: authResult,
+        });
+    }
+}

package/src/custom_auth/core/interaction_client/jit/parameter/JitParams.ts

@@ -0,0 +1,27 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthenticationMethod } from "../../../network_client/custom_auth_api/types/ApiResponseTypes.js";
+
+export interface JitClientParametersBase {
+    correlationId: string;
+    continuationToken: string;
+}
+
+export interface JitChallengeAuthMethodParams extends JitClientParametersBase {
+    authMethod: AuthenticationMethod;
+    verificationContact: string;
+    scopes: string[];
+    username?: string;
+    claims?: string;
+}
+
+export interface JitSubmitChallengeParams extends JitClientParametersBase {
+    grantType: string;
+    challenge?: string;
+    scopes: string[];
+    username?: string;
+    claims?: string;
+}

package/src/custom_auth/core/interaction_client/jit/result/JitActionResult.ts

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthenticationResult } from "../../../../../response/AuthenticationResult.js";
+
+interface JitActionResult {
+    type: string;
+    correlationId: string;
+}
+
+export interface JitVerificationRequiredResult extends JitActionResult {
+    type: typeof JIT_VERIFICATION_REQUIRED_RESULT_TYPE;
+    continuationToken: string;
+    challengeChannel: string;
+    challengeTargetLabel: string;
+    codeLength: number;
+}
+
+export interface JitCompletedResult extends JitActionResult {
+    type: typeof JIT_COMPLETED_RESULT_TYPE;
+    authenticationResult: AuthenticationResult;
+}
+
+// Result type constants
+export const JIT_VERIFICATION_REQUIRED_RESULT_TYPE =
+    "JitVerificationRequiredResult";
+export const JIT_COMPLETED_RESULT_TYPE = "JitCompletedResult";
+
+export function createJitVerificationRequiredResult(
+    input: Omit<JitVerificationRequiredResult, "type">
+): JitVerificationRequiredResult {
+    return {
+        type: JIT_VERIFICATION_REQUIRED_RESULT_TYPE,
+        ...input,
+    };
+}
+
+export function createJitCompletedResult(
+    input: Omit<JitCompletedResult, "type">
+): JitCompletedResult {
+    return {
+        type: JIT_COMPLETED_RESULT_TYPE,
+        ...input,
+    };
+}