@azure/msal-browser 4.23.0 → 4.24.0

package/src/custom_auth/core/auth_flow/AuthFlowErrorBase.ts

@@ -66,7 +66,9 @@ export abstract class AuthFlowErrorBase {
                 this.errorData.subError ===
                     CustomAuthApiSuberror.INVALID_OOB_VALUE) ||
             (this.errorData instanceof InvalidArgumentError &&
-                this.errorData.errorDescription?.includes("code") === true)
+                (this.errorData.errorDescription?.includes("code") ||
+                    this.errorData.errorDescription?.includes("challenge")) ===
+                    true)
         );
     }
 
@@ -140,13 +142,24 @@ export abstract class AuthFlowErrorBase {
         );
     }
 
-    protected isInvalidAuthMethodRegistrationInputError(): boolean {
+    protected isInvalidInputError(): boolean {
         return (
             this.errorData instanceof CustomAuthApiError &&
             this.errorData.error === CustomAuthApiErrorCode.INVALID_REQUEST &&
             this.errorData.errorCodes?.includes(901001) === true
         );
     }
+
+    protected isVerificationContactBlockedError(): boolean {
+        return (
+            this.errorData instanceof CustomAuthApiError &&
+            this.errorData.error === CustomAuthApiErrorCode.INVALID_REQUEST &&
+            this.errorData.errorCodes?.includes(550024) === true &&
+            this.errorData.errorDescription?.includes(
+                "multi-factor authentication method is blocked"
+            ) === true
+        );
+    }
 }
 
 export abstract class AuthActionErrorBase extends AuthFlowErrorBase {

package/src/custom_auth/core/auth_flow/jit/error_type/AuthMethodRegistrationError.ts

@@ -14,7 +14,15 @@ export class AuthMethodRegistrationChallengeMethodError extends AuthActionErrorB
      * @returns true if the input is incorrect, false otherwise.
      */
     isInvalidInput(): boolean {
-        return this.isInvalidAuthMethodRegistrationInputError();
+        return this.isInvalidInputError();
+    }
+
+    /**
+     * Checks if the error is due to the verification contact (e.g., phone number or email) being blocked. Consider using a different email/phone number or a different authentication method.
+     * @returns true if the error is due to the verification contact being blocked, false otherwise.
+     */
+    isVerificationContactBlocked(): boolean {
+        return this.isVerificationContactBlockedError();
     }
 }
 

package/src/custom_auth/core/auth_flow/mfa/error_type/MfaError.ts

@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthActionErrorBase } from "../../AuthFlowErrorBase.js";
+
+/**
+ * Error that occurred during MFA challenge request.
+ */
+export class MfaRequestChallengeError extends AuthActionErrorBase {
+    /**
+     * Checks if the input for MFA challenge is incorrect.
+     * @returns true if the input is incorrect, false otherwise.
+     */
+    isInvalidInput(): boolean {
+        return this.isInvalidInputError();
+    }
+}
+
+/**
+ * Error that occurred during MFA challenge submission.
+ */
+export class MfaSubmitChallengeError extends AuthActionErrorBase {
+    /**
+     * Checks if the submitted challenge code (e.g., OTP code) is incorrect.
+     * @returns true if the challenge code is invalid, false otherwise.
+     */
+    isIncorrectChallenge(): boolean {
+        return this.isInvalidCodeError();
+    }
+}

package/src/custom_auth/core/auth_flow/mfa/result/MfaRequestChallengeResult.ts

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowResultBase } from "../../AuthFlowResultBase.js";
+import { MfaRequestChallengeError } from "../error_type/MfaError.js";
+import { MfaFailedState } from "../state/MfaFailedState.js";
+import type { MfaVerificationRequiredState } from "../state/MfaState.js";
+
+/**
+ * Result of requesting an MFA challenge.
+ * Uses base state type to avoid circular dependencies.
+ */
+export class MfaRequestChallengeResult extends AuthFlowResultBase<
+    MfaRequestChallengeResultState,
+    MfaRequestChallengeError
+> {
+    /**
+     * Creates an MfaRequestChallengeResult with an error.
+     * @param error The error that occurred.
+     * @returns The MfaRequestChallengeResult with error.
+     */
+    static createWithError(error: unknown): MfaRequestChallengeResult {
+        const result = new MfaRequestChallengeResult(new MfaFailedState());
+        result.error = new MfaRequestChallengeError(
+            MfaRequestChallengeResult.createErrorData(error)
+        );
+        return result;
+    }
+
+    /**
+     * Checks if the result indicates that verification is required.
+     * @returns true if verification is required, false otherwise.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    isVerificationRequired(): boolean {
+        return this.state.constructor?.name === "MfaVerificationRequiredState";
+    }
+
+    /**
+     * Checks if the result is in a failed state.
+     * @returns true if the result is failed, false otherwise.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    isFailed(): boolean {
+        return this.state instanceof MfaFailedState;
+    }
+}
+
+/**
+ * The possible states for the MfaRequestChallengeResult.
+ * This includes:
+ * - MfaVerificationRequiredState: The user needs to verify their challenge.
+ * - MfaFailedState: The MFA request failed.
+ */
+export type MfaRequestChallengeResultState =
+    | MfaVerificationRequiredState
+    | MfaFailedState;

package/src/custom_auth/core/auth_flow/mfa/result/MfaSubmitChallengeResult.ts

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowResultBase } from "../../AuthFlowResultBase.js";
+import { MfaSubmitChallengeError } from "../error_type/MfaError.js";
+import { CustomAuthAccountData } from "../../../../get_account/auth_flow/CustomAuthAccountData.js";
+import { MfaCompletedState } from "../state/MfaCompletedState.js";
+import { MfaFailedState } from "../state/MfaFailedState.js";
+
+/**
+ * Result of submitting an MFA challenge.
+ */
+export class MfaSubmitChallengeResult extends AuthFlowResultBase<
+    MfaSubmitChallengeResultState,
+    MfaSubmitChallengeError,
+    CustomAuthAccountData
+> {
+    /**
+     * Creates an MfaSubmitChallengeResult with an error.
+     * @param error The error that occurred.
+     * @returns The MfaSubmitChallengeResult with error.
+     */
+    static createWithError(error: unknown): MfaSubmitChallengeResult {
+        const result = new MfaSubmitChallengeResult(new MfaFailedState());
+        result.error = new MfaSubmitChallengeError(
+            MfaSubmitChallengeResult.createErrorData(error)
+        );
+        return result;
+    }
+
+    /**
+     * Checks if the MFA flow is completed successfully.
+     * @returns true if completed, false otherwise.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    isCompleted(): boolean {
+        return this.state instanceof MfaCompletedState;
+    }
+
+    /**
+     * Checks if the result is in a failed state.
+     * @returns true if the result is failed, false otherwise.
+     * @warning This API is experimental. It may be changed in the future without notice. Do not use in production applications.
+     */
+    isFailed(): boolean {
+        return this.state instanceof MfaFailedState;
+    }
+}
+
+export type MfaSubmitChallengeResultState = MfaCompletedState | MfaFailedState;

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

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowStateBase } from "../../AuthFlowState.js";
+
+/**
+ * State indicating that the MFA flow has completed successfully.
+ */
+export class MfaCompletedState extends AuthFlowStateBase {}

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

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthFlowStateBase } from "../../AuthFlowState.js";
+
+/**
+ * State indicating that the MFA flow has failed.
+ */
+export class MfaFailedState extends AuthFlowStateBase {}

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/interaction_client/CustomAuthInteractionClientBase.ts

@@ -103,7 +103,7 @@ export abstract class CustomAuthInteractionClientBase extends StandardInteractio
 
         const requestTimestamp = Math.round(new Date().getTime() / 1000.0);
 
-        // Save tokens and create authentication result 44s
+        // Save tokens and create authentication result
         const result =
             await this.tokenResponseHandler.handleServerTokenResponse(
                 tokenResponse,

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

@@ -5,15 +5,12 @@
 
 import { CustomAuthInteractionClientBase } from "../CustomAuthInteractionClientBase.js";
 import {
-    JitGetAuthMethodsParams,
     JitChallengeAuthMethodParams,
     JitSubmitChallengeParams,
 } from "./parameter/JitParams.js";
 import {
-    JitGetAuthMethodsResult,
     JitVerificationRequiredResult,
     JitCompletedResult,
-    createJitGetAuthMethodsResult,
     createJitVerificationRequiredResult,
     createJitCompletedResult,
 } from "./result/JitActionResult.js";
@@ -24,7 +21,6 @@ import {
 } from "../../../CustomAuthConstants.js";
 import * as PublicApiId from "../../telemetry/PublicApiId.js";
 import {
-    RegisterIntrospectRequest,
     RegisterChallengeRequest,
     RegisterContinueRequest,
     SignInContinuationTokenRequest,
@@ -34,43 +30,6 @@ import {
  * JIT client for handling just-in-time authentication method registration flows.
  */
 export class JitClient extends CustomAuthInteractionClientBase {
-    /**
-     * Gets available authentication methods for JIT registration.
-     * @param parameters The parameters for getting auth methods.
-     * @returns Promise that resolves to JitGetAuthMethodsResult.
-     */
-    async getAuthMethods(
-        parameters: JitGetAuthMethodsParams
-    ): Promise<JitGetAuthMethodsResult> {
-        const apiId = PublicApiId.JIT_GET_AUTH_METHODS;
-        const telemetryManager = this.initializeServerTelemetryManager(apiId);
-
-        this.logger.verbose(
-            "Calling introspect endpoint for getting auth methods.",
-            parameters.correlationId
-        );
-
-        const request: RegisterIntrospectRequest = {
-            continuation_token: parameters.continuationToken,
-            correlationId: parameters.correlationId,
-            telemetryManager: telemetryManager,
-        };
-
-        const introspectResponse =
-            await this.customAuthApiClient.registerApi.introspect(request);
-
-        this.logger.verbose(
-            "Introspect endpoint called for getting auth methods.",
-            parameters.correlationId
-        );
-
-        return createJitGetAuthMethodsResult({
-            correlationId: introspectResponse.correlation_id,
-            continuationToken: introspectResponse.continuation_token,
-            authMethods: introspectResponse.methods,
-        });
-    }
-
     /**
      * Challenges an authentication method for JIT registration.
      * @param parameters The parameters for challenging the auth method.
@@ -195,7 +154,7 @@ export class JitClient extends CustomAuthInteractionClientBase {
         const authResult = await this.handleTokenResponse(
             tokenResponse,
             scopes,
-            continueResponse.correlation_id
+            tokenResponse.correlation_id || continueResponse.correlation_id
         );
 
         return createJitCompletedResult({

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

@@ -10,8 +10,6 @@ export interface JitClientParametersBase {
     continuationToken: string;
 }
 
-export type JitGetAuthMethodsParams = JitClientParametersBase;
-
 export interface JitChallengeAuthMethodParams extends JitClientParametersBase {
     authMethod: AuthenticationMethod;
     verificationContact: string;

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

@@ -4,25 +4,15 @@
  */
 
 import { AuthenticationResult } from "../../../../../response/AuthenticationResult.js";
-import { AuthenticationMethod } from "../../../network_client/custom_auth_api/types/ApiResponseTypes.js";
 
 interface JitActionResult {
     type: string;
     correlationId: string;
 }
 
-interface JitContinuationTokenResult extends JitActionResult {
-    continuationToken: string;
-}
-
-export interface JitGetAuthMethodsResult extends JitContinuationTokenResult {
-    type: typeof JIT_GET_AUTH_METHODS_RESULT_TYPE;
-    authMethods: AuthenticationMethod[];
-}
-
-export interface JitVerificationRequiredResult
-    extends JitContinuationTokenResult {
+export interface JitVerificationRequiredResult extends JitActionResult {
     type: typeof JIT_VERIFICATION_REQUIRED_RESULT_TYPE;
+    continuationToken: string;
     challengeChannel: string;
     challengeTargetLabel: string;
     codeLength: number;
@@ -34,20 +24,10 @@ export interface JitCompletedResult extends JitActionResult {
 }
 
 // Result type constants
-export const JIT_GET_AUTH_METHODS_RESULT_TYPE = "JitGetAuthMethodsResult";
 export const JIT_VERIFICATION_REQUIRED_RESULT_TYPE =
     "JitVerificationRequiredResult";
 export const JIT_COMPLETED_RESULT_TYPE = "JitCompletedResult";
 
-export function createJitGetAuthMethodsResult(
-    input: Omit<JitGetAuthMethodsResult, "type">
-): JitGetAuthMethodsResult {
-    return {
-        type: JIT_GET_AUTH_METHODS_RESULT_TYPE,
-        ...input,
-    };
-}
-
 export function createJitVerificationRequiredResult(
     input: Omit<JitVerificationRequiredResult, "type">
 ): JitVerificationRequiredResult {