@azure/msal-browser 4.23.0 → 4.24.0

package/src/custom_auth/core/interaction_client/mfa/MfaClient.ts

@@ -0,0 +1,148 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CustomAuthInteractionClientBase } from "../CustomAuthInteractionClientBase.js";
+import {
+    MfaRequestChallengeParams,
+    MfaSubmitChallengeParams,
+} from "./parameter/MfaClientParameters.js";
+import {
+    MfaVerificationRequiredResult,
+    MfaCompletedResult,
+    createMfaVerificationRequiredResult,
+    createMfaCompletedResult,
+} from "./result/MfaActionResult.js";
+import {
+    DefaultCustomAuthApiCodeLength,
+    ChallengeType,
+    GrantType,
+} from "../../../CustomAuthConstants.js";
+import * as PublicApiId from "../../telemetry/PublicApiId.js";
+import {
+    SignInChallengeRequest,
+    SignInOobTokenRequest,
+} from "../../network_client/custom_auth_api/types/ApiRequestTypes.js";
+import { ensureArgumentIsNotEmptyString } from "../../utils/ArgumentValidator.js";
+import { CustomAuthApiError } from "../../error/CustomAuthApiError.js";
+import * as CustomAuthApiErrorCode from "../../network_client/custom_auth_api/types/ApiErrorCodes.js";
+
+/**
+ * MFA client for handling multi-factor authentication flows.
+ */
+export class MfaClient extends CustomAuthInteractionClientBase {
+    /**
+     * Requests an MFA challenge to be sent to the user.
+     * @param parameters The parameters for requesting the challenge.
+     * @returns Promise that resolves to either MfaVerificationRequiredResult.
+     */
+    async requestChallenge(
+        parameters: MfaRequestChallengeParams
+    ): Promise<MfaVerificationRequiredResult> {
+        const apiId = PublicApiId.MFA_REQUEST_CHALLENGE;
+        const telemetryManager = this.initializeServerTelemetryManager(apiId);
+
+        this.logger.verbose(
+            "Calling challenge endpoint for MFA.",
+            parameters.correlationId
+        );
+
+        const challengeReq: SignInChallengeRequest = {
+            challenge_type: this.getChallengeTypes(parameters.challengeType),
+            continuation_token: parameters.continuationToken,
+            id: parameters.authMethodId,
+            correlationId: parameters.correlationId,
+            telemetryManager: telemetryManager,
+        };
+
+        const challengeResponse =
+            await this.customAuthApiClient.signInApi.requestChallenge(
+                challengeReq
+            );
+
+        this.logger.verbose(
+            "Challenge endpoint called for MFA.",
+            parameters.correlationId
+        );
+
+        if (challengeResponse.challenge_type === ChallengeType.OOB) {
+            // Verification required - code will be sent
+            return createMfaVerificationRequiredResult({
+                correlationId: challengeResponse.correlation_id,
+                continuationToken: challengeResponse.continuation_token ?? "",
+                challengeChannel: challengeResponse.challenge_channel ?? "",
+                challengeTargetLabel:
+                    challengeResponse.challenge_target_label ?? "",
+                codeLength:
+                    challengeResponse.code_length ??
+                    DefaultCustomAuthApiCodeLength,
+                bindingMethod: challengeResponse.binding_method ?? "",
+            });
+        }
+
+        this.logger.error(
+            `Unsupported challenge type '${challengeResponse.challenge_type}' for MFA.`,
+            parameters.correlationId
+        );
+
+        throw new CustomAuthApiError(
+            CustomAuthApiErrorCode.UNSUPPORTED_CHALLENGE_TYPE,
+            `Unsupported challenge type '${challengeResponse.challenge_type}'.`,
+            challengeResponse.correlation_id
+        );
+    }
+
+    /**
+     * Submits the MFA challenge response (e.g., OTP code).
+     * @param parameters The parameters for submitting the challenge.
+     * @returns Promise that resolves to MfaCompletedResult.
+     */
+    async submitChallenge(
+        parameters: MfaSubmitChallengeParams
+    ): Promise<MfaCompletedResult> {
+        ensureArgumentIsNotEmptyString(
+            "parameters.challenge",
+            parameters.challenge,
+            parameters.correlationId
+        );
+
+        const apiId = PublicApiId.MFA_SUBMIT_CHALLENGE;
+        const telemetryManager = this.initializeServerTelemetryManager(apiId);
+        const scopes = this.getScopes(parameters.scopes);
+
+        const request: SignInOobTokenRequest = {
+            continuation_token: parameters.continuationToken,
+            oob: parameters.challenge,
+            grant_type: GrantType.MFA_OOB,
+            scope: scopes.join(" "),
+            correlationId: parameters.correlationId,
+            telemetryManager: telemetryManager,
+            ...(parameters.claims && {
+                claims: parameters.claims,
+            }),
+        };
+
+        this.logger.verbose(
+            "Calling token endpoint for MFA challenge submission.",
+            parameters.correlationId
+        );
+
+        const tokenResponse =
+            await this.customAuthApiClient.signInApi.requestTokensWithOob(
+                request
+            );
+
+        // Save tokens and create authentication result
+        const result = await this.handleTokenResponse(
+            tokenResponse,
+            scopes,
+            tokenResponse.correlation_id ?? parameters.correlationId
+        );
+
+        return createMfaCompletedResult({
+            correlationId: parameters.correlationId,
+            authenticationResult: result,
+        });
+    }
+}

package/src/custom_auth/core/interaction_client/mfa/parameter/MfaClientParameters.ts

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export interface MfaClientParametersBase {
+    correlationId: string;
+    continuationToken: string;
+}
+
+export interface MfaRequestChallengeParams extends MfaClientParametersBase {
+    challengeType: string[];
+    authMethodId: string;
+}
+
+export interface MfaSubmitChallengeParams extends MfaClientParametersBase {
+    challenge: string;
+    scopes: string[];
+    claims?: string;
+}

package/src/custom_auth/core/interaction_client/mfa/result/MfaActionResult.ts

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AuthenticationResult } from "../../../../../response/AuthenticationResult.js";
+
+interface MfaActionResult {
+    type: string;
+    correlationId: string;
+}
+
+export interface MfaVerificationRequiredResult extends MfaActionResult {
+    type: typeof MFA_VERIFICATION_REQUIRED_RESULT_TYPE;
+    continuationToken: string;
+    challengeChannel: string;
+    challengeTargetLabel: string;
+    codeLength: number;
+    bindingMethod: string;
+}
+
+export interface MfaCompletedResult extends MfaActionResult {
+    type: typeof MFA_COMPLETED_RESULT_TYPE;
+    authenticationResult: AuthenticationResult;
+}
+
+// Result type constants
+export const MFA_VERIFICATION_REQUIRED_RESULT_TYPE =
+    "MfaVerificationRequiredResult";
+export const MFA_COMPLETED_RESULT_TYPE = "MfaCompletedResult";
+
+export function createMfaVerificationRequiredResult(
+    input: Omit<MfaVerificationRequiredResult, "type">
+): MfaVerificationRequiredResult {
+    return {
+        type: MFA_VERIFICATION_REQUIRED_RESULT_TYPE,
+        ...input,
+    };
+}
+
+export function createMfaCompletedResult(
+    input: Omit<MfaCompletedResult, "type">
+): MfaCompletedResult {
+    return {
+        type: MFA_COMPLETED_RESULT_TYPE,
+        ...input,
+    };
+}

package/src/custom_auth/core/network_client/custom_auth_api/CustomAuthApiEndpoint.ts

@@ -6,6 +6,7 @@
 export const SIGNIN_INITIATE = "/oauth2/v2.0/initiate";
 export const SIGNIN_CHALLENGE = "/oauth2/v2.0/challenge";
 export const SIGNIN_TOKEN = "/oauth2/v2.0/token";
+export const SIGNIN_INTROSPECT = "/oauth2/v2.0/introspect";
 
 export const SIGNUP_START = "/signup/v1.0/start";
 export const SIGNUP_CHALLENGE = "/signup/v1.0/challenge";

package/src/custom_auth/core/network_client/custom_auth_api/SignInApiClient.ts

@@ -14,12 +14,14 @@ import {
     SignInChallengeRequest,
     SignInContinuationTokenRequest,
     SignInInitiateRequest,
+    SignInIntrospectRequest,
     SignInOobTokenRequest,
     SignInPasswordTokenRequest,
 } from "./types/ApiRequestTypes.js";
 import {
     SignInChallengeResponse,
     SignInInitiateResponse,
+    SignInIntrospectResponse,
     SignInTokenResponse,
 } from "./types/ApiResponseTypes.js";
 
@@ -128,7 +130,7 @@ export class SignInApiClient extends BaseApiClient {
                 continuation_token: params.continuation_token,
                 scope: params.scope,
                 oob: params.oob,
-                grant_type: GrantType.OOB,
+                grant_type: params.grant_type,
                 ...(params.claims && { claims: params.claims }),
             },
             params.telemetryManager,
@@ -153,6 +155,30 @@ export class SignInApiClient extends BaseApiClient {
         );
     }
 
+    /**
+     * Requests available authentication methods for MFA
+     * @param continuationToken Token from previous response
+     */
+    async requestAuthMethods(
+        params: SignInIntrospectRequest
+    ): Promise<SignInIntrospectResponse> {
+        const result = await this.request<SignInIntrospectResponse>(
+            CustomAuthApiEndpoint.SIGNIN_INTROSPECT,
+            {
+                continuation_token: params.continuation_token,
+            },
+            params.telemetryManager,
+            params.correlationId
+        );
+
+        this.ensureContinuationTokenIsValid(
+            result.continuation_token,
+            params.correlationId
+        );
+
+        return result;
+    }
+
     private async requestTokens(
         requestData: Record<string, string | boolean>,
         telemetryManager: ServerTelemetryManager,

package/src/custom_auth/core/network_client/custom_auth_api/types/ApiRequestTypes.ts

@@ -3,6 +3,7 @@
  * Licensed under the MIT License.
  */
 
+import { GrantType } from "../../../../CustomAuthConstants.js";
 import { ApiRequestBase } from "./ApiTypesBase.js";
 
 /* Sign-in API request types */
@@ -29,12 +30,17 @@ export interface SignInPasswordTokenRequest extends SignInTokenRequestBase {
 
 export interface SignInOobTokenRequest extends SignInTokenRequestBase {
     oob: string;
+    grant_type: typeof GrantType.OOB | typeof GrantType.MFA_OOB;
 }
 
 export interface SignInContinuationTokenRequest extends SignInTokenRequestBase {
     username?: string;
 }
 
+export interface SignInIntrospectRequest extends ApiRequestBase {
+    continuation_token: string;
+}
+
 /* Sign-up API request types */
 export interface SignUpStartRequest extends ApiRequestBase {
     username: string;

package/src/custom_auth/core/network_client/custom_auth_api/types/ApiResponseTypes.ts

@@ -42,7 +42,12 @@ export interface AuthenticationMethod {
     id: string;
     challenge_type: string;
     challenge_channel: string;
-    login_hint: string;
+    login_hint?: string;
+}
+
+export interface SignInIntrospectResponse extends ApiResponseBase {
+    continuation_token: string;
+    methods: AuthenticationMethod[];
 }
 
 /* Sign-up API response types */

package/src/custom_auth/core/network_client/custom_auth_api/types/ApiSuberrors.ts

@@ -13,3 +13,4 @@ export const INVALID_OOB_VALUE = "invalid_oob_value";
 export const ATTRIBUTE_VALIATION_FAILED = "attribute_validation_failed";
 export const NATIVEAUTHAPI_DISABLED = "nativeauthapi_disabled";
 export const REGISTRATION_REQUIRED = "registration_required";
+export const MFA_REQUIRED = "mfa_required";

package/src/custom_auth/core/telemetry/PublicApiId.ts

@@ -37,6 +37,9 @@ export const ACCOUNT_SIGN_OUT = 100062;
 export const ACCOUNT_GET_ACCESS_TOKEN = 100063;
 
 // JIT (Just-In-Time) Auth Method Registration
-export const JIT_GET_AUTH_METHODS = 100081;
-export const JIT_CHALLENGE_AUTH_METHOD = 100082;
-export const JIT_SUBMIT_CHALLENGE = 100083;
+export const JIT_CHALLENGE_AUTH_METHOD = 100081;
+export const JIT_SUBMIT_CHALLENGE = 100082;
+
+// MFA
+export const MFA_REQUEST_CHALLENGE = 100101;
+export const MFA_SUBMIT_CHALLENGE = 100102;

package/src/custom_auth/sign_in/auth_flow/state/SignInCodeRequiredState.ts

@@ -13,6 +13,7 @@ import { SignInSubmitCodeResult } from "../result/SignInSubmitCodeResult.js";
 import { SignInCodeRequiredStateParameters } from "./SignInStateParameters.js";
 import { SignInState } from "./SignInState.js";
 import { SignInCompletedState } from "./SignInCompletedState.js";
+import { SIGN_IN_COMPLETED_RESULT_TYPE } from "../../interaction_client/result/SignInActionResult.js";
 
 /*
  * Sign-in code required state.
@@ -45,7 +46,7 @@ export class SignInCodeRequiredState extends SignInState<SignInCodeRequiredState
                 this.stateParameters.correlationId
             );
 
-            const completedResult =
+            const submitCodeResult =
                 await this.stateParameters.signInClient.submitCode(
                     submitCodeParams
                 );
@@ -55,18 +56,27 @@ export class SignInCodeRequiredState extends SignInState<SignInCodeRequiredState
                 this.stateParameters.correlationId
             );
 
-            const accountInfo = new CustomAuthAccountData(
-                completedResult.authenticationResult.account,
-                this.stateParameters.config,
-                this.stateParameters.cacheClient,
-                this.stateParameters.logger,
-                this.stateParameters.correlationId
-            );
+            if (submitCodeResult.type === SIGN_IN_COMPLETED_RESULT_TYPE) {
+                const accountInfo = new CustomAuthAccountData(
+                    submitCodeResult.authenticationResult.account,
+                    this.stateParameters.config,
+                    this.stateParameters.cacheClient,
+                    this.stateParameters.logger,
+                    this.stateParameters.correlationId
+                );
 
-            return new SignInSubmitCodeResult(
-                new SignInCompletedState(),
-                accountInfo
-            );
+                return new SignInSubmitCodeResult(
+                    new SignInCompletedState(),
+                    accountInfo
+                );
+            } else {
+                // Unexpected result type
+                const result = submitCodeResult as { type: string };
+                const error = new Error(
+                    `Unexpected result type: ${result.type}`
+                );
+                return SignInSubmitCodeResult.createWithError(error);
+            }
         } catch (error) {
             this.stateParameters.logger.errorPii(
                 `Failed to submit code for sign-in. Error: ${error}.`,

package/src/custom_auth/sign_in/interaction_client/SignInClient.ts

@@ -6,10 +6,14 @@
 import {
     ChallengeType,
     DefaultCustomAuthApiCodeLength,
+    GrantType,
 } from "../../CustomAuthConstants.js";
 import { CustomAuthApiError } from "../../core/error/CustomAuthApiError.js";
 import * as CustomAuthApiErrorCode from "../../core/network_client/custom_auth_api/types/ApiErrorCodes.js";
-import { REGISTRATION_REQUIRED } from "../../core/network_client/custom_auth_api/types/ApiSuberrors.js";
+import {
+    MFA_REQUIRED,
+    REGISTRATION_REQUIRED,
+} from "../../core/network_client/custom_auth_api/types/ApiSuberrors.js";
 
 import { CustomAuthInteractionClientBase } from "../../core/interaction_client/CustomAuthInteractionClientBase.js";
 import {
@@ -29,6 +33,8 @@ import {
     SignInCompletedResult,
     SignInPasswordRequiredResult,
     SignInJitRequiredResult,
+    SignInMfaRequiredResult,
+    createSignInMfaRequiredResult,
 } from "./result/SignInActionResult.js";
 import * as PublicApiId from "../../core/telemetry/PublicApiId.js";
 import {
@@ -38,6 +44,7 @@ import {
     SignInOobTokenRequest,
     SignInPasswordTokenRequest,
     RegisterIntrospectRequest,
+    SignInIntrospectRequest,
 } from "../../core/network_client/custom_auth_api/types/ApiRequestTypes.js";
 import { SignInTokenResponse } from "../../core/network_client/custom_auth_api/types/ApiResponseTypes.js";
 import {
@@ -135,7 +142,11 @@ export class SignInClient extends CustomAuthInteractionClientBase {
      */
     async submitCode(
         parameters: SignInSubmitCodeParams
-    ): Promise<SignInCompletedResult> {
+    ): Promise<
+        | SignInCompletedResult
+        | SignInJitRequiredResult
+        | SignInMfaRequiredResult
+    > {
         ensureArgumentIsNotEmptyString(
             "parameters.code",
             parameters.code,
@@ -149,6 +160,7 @@ export class SignInClient extends CustomAuthInteractionClientBase {
         const request: SignInOobTokenRequest = {
             continuation_token: parameters.continuationToken,
             oob: parameters.code,
+            grant_type: GrantType.OOB,
             scope: scopes.join(" "),
             correlationId: parameters.correlationId,
             telemetryManager: telemetryManager,
@@ -157,18 +169,15 @@ export class SignInClient extends CustomAuthInteractionClientBase {
             }),
         };
 
-        const result = this.performTokenRequest(
+        return this.performTokenRequest(
             () =>
                 this.customAuthApiClient.signInApi.requestTokensWithOob(
                     request
                 ),
             scopes,
             parameters.correlationId,
-            telemetryManager,
-            false // Don't handle JIT for code submission
+            telemetryManager
         );
-
-        return result as Promise<SignInCompletedResult>;
     }
 
     /**
@@ -178,7 +187,11 @@ export class SignInClient extends CustomAuthInteractionClientBase {
      */
     async submitPassword(
         parameters: SignInSubmitPasswordParams
-    ): Promise<SignInCompletedResult | SignInJitRequiredResult> {
+    ): Promise<
+        | SignInCompletedResult
+        | SignInJitRequiredResult
+        | SignInMfaRequiredResult
+    > {
         ensureArgumentIsNotEmptyString(
             "parameters.password",
             parameters.password,
@@ -207,8 +220,7 @@ export class SignInClient extends CustomAuthInteractionClientBase {
                 ),
             scopes,
             parameters.correlationId,
-            telemetryManager,
-            true // Handle JIT for password submission
+            telemetryManager
         );
     }
 
@@ -219,7 +231,11 @@ export class SignInClient extends CustomAuthInteractionClientBase {
      */
     async signInWithContinuationToken(
         parameters: SignInContinuationTokenParams
-    ): Promise<SignInCompletedResult | SignInJitRequiredResult> {
+    ): Promise<
+        | SignInCompletedResult
+        | SignInJitRequiredResult
+        | SignInMfaRequiredResult
+    > {
         const apiId = this.getPublicApiIdBySignInScenario(
             parameters.signInScenario,
             parameters.correlationId
@@ -247,9 +263,8 @@ export class SignInClient extends CustomAuthInteractionClientBase {
                 ),
             scopes,
             parameters.correlationId,
-            telemetryManager,
-            true // Handle JIT for continuation token sign-in (e.g., after sign-up or SSPR)
-        ) as Promise<SignInCompletedResult | SignInJitRequiredResult>;
+            telemetryManager
+        );
     }
 
     /**
@@ -257,16 +272,19 @@ export class SignInClient extends CustomAuthInteractionClientBase {
      * @param tokenEndpointCaller Function that calls the specific token endpoint
      * @param scopes Scopes for the token request
      * @param correlationId Correlation ID for logging and result
-     * @param handleJit Whether to handle JIT required errors or throw them
-     * @returns SignInCompletedResult with authentication result
+     * @param telemetryManager Telemetry manager for telemetry logging
+     * @returns SignInCompletedResult | SignInJitRequiredResult | SignInMfaRequiredResult with authentication result
      */
     private async performTokenRequest(
         tokenEndpointCaller: () => Promise<SignInTokenResponse>,
         scopes: string[],
         correlationId: string,
-        telemetryManager: ServerTelemetryManager,
-        handleJit: boolean
-    ): Promise<SignInCompletedResult | SignInJitRequiredResult> {
+        telemetryManager: ServerTelemetryManager
+    ): Promise<
+        | SignInCompletedResult
+        | SignInJitRequiredResult
+        | SignInMfaRequiredResult
+    > {
         this.logger.verbose(
             "Calling token endpoint for sign in.",
             correlationId
@@ -292,34 +310,23 @@ export class SignInClient extends CustomAuthInteractionClientBase {
             });
         } catch (error) {
             if (
-                handleJit &&
                 error instanceof CustomAuthApiError &&
                 error.subError === REGISTRATION_REQUIRED
             ) {
-                this.logger.verbose(
-                    "Auth method registration required for sign in.",
+                return this.handleJitRequiredError(
+                    error,
+                    telemetryManager,
                     correlationId
                 );
-
-                // Call register introspect endpoint to get available authentication methods
-                const introspectRequest: RegisterIntrospectRequest = {
-                    continuation_token: error.continuationToken ?? "",
-                    correlationId: error.correlationId ?? correlationId,
+            } else if (
+                error instanceof CustomAuthApiError &&
+                error.subError === MFA_REQUIRED
+            ) {
+                return this.handleMfaRequiredError(
+                    error,
                     telemetryManager,
-                };
-
-                const introspectResponse =
-                    await this.customAuthApiClient.registerApi.introspect(
-                        introspectRequest
-                    );
-
-                return createSignInJitRequiredResult({
-                    correlationId:
-                        introspectResponse.correlation_id ?? correlationId,
-                    continuationToken:
-                        introspectResponse.continuation_token ?? "",
-                    authMethods: introspectResponse.methods,
-                });
+                    correlationId
+                );
             }
 
             // Re-throw any other errors or JIT errors when handleJit is false
@@ -404,4 +411,79 @@ export class SignInClient extends CustomAuthInteractionClientBase {
                 );
         }
     }
+
+    private async handleJitRequiredError(
+        error: CustomAuthApiError,
+        telemetryManager: ServerTelemetryManager,
+        correlationId: string
+    ): Promise<SignInJitRequiredResult> {
+        this.logger.verbose(
+            "Auth method registration required for sign in.",
+            correlationId
+        );
+
+        // Call register introspect endpoint to get available authentication methods
+        const introspectRequest: RegisterIntrospectRequest = {
+            continuation_token: error.continuationToken ?? "",
+            correlationId: error.correlationId ?? correlationId,
+            telemetryManager,
+        };
+
+        this.logger.verbose(
+            "Calling introspect endpoint for getting auth methods.",
+            correlationId
+        );
+
+        const introspectResponse =
+            await this.customAuthApiClient.registerApi.introspect(
+                introspectRequest
+            );
+
+        this.logger.verbose(
+            "Introspect endpoint called for getting auth methods.",
+            introspectResponse.correlation_id ?? correlationId
+        );
+
+        return createSignInJitRequiredResult({
+            correlationId: introspectResponse.correlation_id ?? correlationId,
+            continuationToken: introspectResponse.continuation_token ?? "",
+            authMethods: introspectResponse.methods,
+        });
+    }
+
+    private async handleMfaRequiredError(
+        error: CustomAuthApiError,
+        telemetryManager: ServerTelemetryManager,
+        correlationId: string
+    ): Promise<SignInMfaRequiredResult> {
+        this.logger.verbose("MFA required for sign in.", correlationId);
+
+        // Call sign-in introspect endpoint to get available MFA methods
+        const introspectRequest: SignInIntrospectRequest = {
+            continuation_token: error.continuationToken ?? "",
+            correlationId: error.correlationId ?? correlationId,
+            telemetryManager,
+        };
+
+        this.logger.verbose(
+            "Calling introspect endpoint for MFA auth methods.",
+            correlationId
+        );
+
+        const introspectResponse =
+            await this.customAuthApiClient.signInApi.requestAuthMethods(
+                introspectRequest
+            );
+
+        this.logger.verbose(
+            "Introspect endpoint called for MFA auth methods.",
+            introspectResponse.correlation_id ?? correlationId
+        );
+
+        return createSignInMfaRequiredResult({
+            correlationId: introspectResponse.correlation_id ?? correlationId,
+            continuationToken: introspectResponse.continuation_token ?? "",
+            authMethods: introspectResponse.methods,
+        });
+    }
 }