Add backward compatibility support (#7962)

This pull request adds support for client capabilities in the custom
authentication flows of `@azure/msal-browser`, enabling the client to
declare which authentication features it supports when interacting with
the Microsoft Entra backend. It also refactors how redirect-required
errors are handled and simplifies error classes related to sign-in,
sign-up, and password reset flows.

**Custom Authentication Capabilities Support:**

* Added a `capabilities` field to `CustomAuthOptions`, allowing clients
to specify supported features (e.g., MFA, registration) in the
configuration
(`lib/msal-browser/src/custom_auth/configuration/CustomAuthConfiguration.ts`).
[[1]](diffhunk://#diff-5e18147940e49db10c140f6f1547464c2ca5a6a5e49767b129568bca042d4e68R14)
[[2]](diffhunk://#diff-f98ffa0d9403f1827bd9bbad2ffe5b540194bc8da456e63d52c2958cb53309bbR48-R52)
* Propagated the `capabilities` array through the `CustomAuthApiClient`
and down to the `SignInApiClient`, `SignupApiClient`, and
`ResetPasswordApiClient` classes, which now include these capabilities
in their API requests (`CustomAuthApiClient.ts`, `SignInApiClient.ts`,
`SignupApiClient.ts`, `ResetPasswordApiClient.ts`).
[[1]](diffhunk://#diff-e4bffa17d39a62bd6d7c57db17850e1f22788b8646f226554c95fd690ee8de75L20-R39)
[[2]](diffhunk://#diff-e9a2087346a3cd1aba8abd540d01c2d10396a55b66935e8c03b59383251ab4f8L115-R116)
[[3]](diffhunk://#diff-e7a4d56565aaa98f4c89dc3954e27233d4f5c480f180a86478a3901da6f90ae5R12)
[[4]](diffhunk://#diff-e7a4d56565aaa98f4c89dc3954e27233d4f5c480f180a86478a3901da6f90ae5R31-R42)
[[5]](diffhunk://#diff-e7a4d56565aaa98f4c89dc3954e27233d4f5c480f180a86478a3901da6f90ae5R54-R57)
[[6]](diffhunk://#diff-0f28d0a272570d542dad8bd119415ae0363070a901540fc455e8b16f10e3c1a6R10)
[[7]](diffhunk://#diff-0f28d0a272570d542dad8bd119415ae0363070a901540fc455e8b16f10e3c1a6R27-R38)
[[8]](diffhunk://#diff-0f28d0a272570d542dad8bd119415ae0363070a901540fc455e8b16f10e3c1a6R52-R55)
[[9]](diffhunk://#diff-f074b0fbd643127fd46c37085055bad34adf3b7d1b9d4d4fc7fe0851bef5fe50R8)
[[10]](diffhunk://#diff-f074b0fbd643127fd46c37085055bad34adf3b7d1b9d4d4fc7fe0851bef5fe50R24-R35)
[[11]](diffhunk://#diff-f074b0fbd643127fd46c37085055bad34adf3b7d1b9d4d4fc7fe0851bef5fe50R49-R52)
* Updated API request type definitions to include the optional
`capabilities` field (`ApiRequestTypes.ts`).
[[1]](diffhunk://#diff-323a83bb10ebc94100586aadee937c29d77db9714dfed3e923894466976e5214R12)
[[2]](diffhunk://#diff-323a83bb10ebc94100586aadee937c29d77db9714dfed3e923894466976e5214R44)
[[3]](diffhunk://#diff-323a83bb10ebc94100586aadee937c29d77db9714dfed3e923894466976e5214R75)

**Error Handling Improvements:**

* Centralized the logic for determining if a redirect is required into
the base error class (`AuthFlowErrorBase.ts`), removing redundant
`isRedirectRequired` methods from specific error subclasses
(`SignInError.ts`, `SignUpError.ts`, `ResetPasswordError.ts`).
[[1]](diffhunk://#diff-d258b0a5af2cbf80110d814acf0b7df45e55bb0103bf53138e66020a93700a8bR152-R159)
[[2]](diffhunk://#diff-9bd88fec8e83fbb9e1d8e770f5ddc0cc395bda13033c70c787b85970f8d80841L34-L41)
[[3]](diffhunk://#diff-9bd88fec8e83fbb9e1d8e770f5ddc0cc395bda13033c70c787b85970f8d80841L78-R72)
[[4]](diffhunk://#diff-ddccd76ab42f6c83000ec1e1857a6322d82dbf78b3e9d47c6fa07d4c0e9488bbL49-L56)
[[5]](diffhunk://#diff-ddccd76ab42f6c83000ec1e1857a6322d82dbf78b3e9d47c6fa07d4c0e9488bbL79-R71)
[[6]](diffhunk://#diff-6992ffb0801330c7612d8d2fd7b160539d6e05284428a22dbf784b72c651702dL56-L63)
[[7]](diffhunk://#diff-6992ffb0801330c7612d8d2fd7b160539d6e05284428a22dbf784b72c651702dL76-L83)
[[8]](diffhunk://#diff-6992ffb0801330c7612d8d2fd7b160539d6e05284428a22dbf784b72c651702dL94-L101)
[[9]](diffhunk://#diff-6992ffb0801330c7612d8d2fd7b160539d6e05284428a22dbf784b72c651702dL120-R98)
* Simplified resend code error classes for sign-in, sign-up, and reset
password flows by removing unnecessary methods (`SignInResendCodeError`,
`SignUpResendCodeError`, `ResetPasswordResendCodeError`).
[[1]](diffhunk://#diff-9bd88fec8e83fbb9e1d8e770f5ddc0cc395bda13033c70c787b85970f8d80841L78-R72)
[[2]](diffhunk://#diff-ddccd76ab42f6c83000ec1e1857a6322d82dbf78b3e9d47c6fa07d4c0e9488bbL79-R71)
[[3]](diffhunk://#diff-6992ffb0801330c7612d8d2fd7b160539d6e05284428a22dbf784b72c651702dL120-R98)

**Redirect Error Enhancements:**

* Enhanced the `RedirectError` class to accept and display a more
specific redirect reason from the server, improving error messaging
(`CustomAuthApiError.ts`, `BaseApiClient.ts`).
[[1]](diffhunk://#diff-2dd77566c3e5ea80a8842413c962e06065c43583c961afb159cda2b07e87c5ebL13-R17)
[[2]](diffhunk://#diff-3a0d4ccac21db6d650f33cd543d93dd57d0505da0cc82a8cd38cfedbd5b3b55eL131-R134)

**Other:**

* Added a patch change file for backward compatibility support for
`@azure/msal-browser`.

Author: yongdiw

change/@azure-msal-browser-3682a32a-64a8-4932-85e9-7fb173829fb9.json

@@ -0,0 +1,7 @@
+{
+    "type": "patch",
+    "comment": "Backward compability support #7962",
+    "packageName": "@azure/msal-browser",
+    "email": "[email protected]",
+    "dependentChangeType": "patch"
+}

lib/msal-browser/src/custom_auth/configuration/CustomAuthConfiguration.ts

@@ -11,6 +11,7 @@ import {
 export type CustomAuthOptions = {
     challengeTypes?: Array<string>;
     authApiProxyUrl: string;
+    capabilities?: Array<string>;
 };
 
 export type CustomAuthConfiguration = Configuration & {

lib/msal-browser/src/custom_auth/controller/CustomAuthStandardController.ts

@@ -112,7 +112,8 @@ export class CustomAuthStandardController
                 new CustomAuthApiClient(
                     this.authority.getCustomAuthApiDomain(),
                     this.customAuthConfig.auth.clientId,
-                    new FetchHttpClient(this.logger)
+                    new FetchHttpClient(this.logger),
+                    this.customAuthConfig.customAuth?.capabilities?.join(" ")
                 ),
             this.authority
         );

lib/msal-browser/src/custom_auth/core/auth_flow/AuthFlowErrorBase.ts

@@ -149,4 +149,12 @@ export abstract class AuthActionErrorBase extends AuthFlowErrorBase {
     isTokenExpired(): boolean {
         return this.isTokenExpiredError();
     }
+
+    /**
+     * Check if client app supports the challenge type configured in Entra.
+     * @returns {boolean} True if client app doesn't support the challenge type configured in Entra, "loginPopup" function is required to continue the operation.
+     */
+    isRedirectRequired(): boolean {
+        return this.isRedirectError();
+    }
 }

lib/msal-browser/src/custom_auth/core/error/CustomAuthApiError.ts

@@ -10,10 +10,11 @@ import { CustomAuthError } from "./CustomAuthError.js";
  * Error when no required authentication method by Microsoft Entra is supported
  */
 export class RedirectError extends CustomAuthError {
-    constructor(correlationId?: string) {
+    constructor(correlationId?: string, public redirectReason?: string) {
         super(
             "redirect",
-            "No required authentication method by Microsoft Entra is supported, a fallback to the web-based authentication flow is needed.",
+            redirectReason ||
+                "Redirect Error, a fallback to the browser-delegated authentication is needed. Use loginPopup instead.",
             correlationId
         );
         Object.setPrototypeOf(this, RedirectError.prototype);

lib/msal-browser/src/custom_auth/core/network_client/custom_auth_api/BaseApiClient.ts

@@ -128,7 +128,10 @@ export abstract class BaseApiClient {
                 typeof responseData === "object" &&
                 responseData.challenge_type === ChallengeType.REDIRECT
             ) {
-                throw new RedirectError(correlationId);
+                throw new RedirectError(
+                    correlationId,
+                    responseData.redirect_reason
+                );
             }
 
             return {

lib/msal-browser/src/custom_auth/core/network_client/custom_auth_api/CustomAuthApiClient.ts

@@ -17,22 +17,26 @@ export class CustomAuthApiClient implements ICustomAuthApiClient {
     constructor(
         customAuthApiBaseUrl: string,
         clientId: string,
-        httpClient: IHttpClient
+        httpClient: IHttpClient,
+        capabilities?: string
     ) {
         this.signInApi = new SignInApiClient(
             customAuthApiBaseUrl,
             clientId,
-            httpClient
+            httpClient,
+            capabilities
         );
         this.signUpApi = new SignupApiClient(
             customAuthApiBaseUrl,
             clientId,
-            httpClient
+            httpClient,
+            capabilities
         );
         this.resetPasswordApi = new ResetPasswordApiClient(
             customAuthApiBaseUrl,
             clientId,
-            httpClient
+            httpClient,
+            capabilities
         );
     }
 }

lib/msal-browser/src/custom_auth/core/network_client/custom_auth_api/ResetPasswordApiClient.ts

@@ -9,6 +9,7 @@ import {
 } from "../../../CustomAuthConstants.js";
 import { CustomAuthApiError } from "../../error/CustomAuthApiError.js";
 import { BaseApiClient } from "./BaseApiClient.js";
+import { IHttpClient } from "../http_client/IHttpClient.js";
 import * as CustomAuthApiEndpoint from "./CustomAuthApiEndpoint.js";
 import * as CustomAuthApiErrorCode from "./types/ApiErrorCodes.js";
 import {
@@ -27,6 +28,18 @@ import {
 } from "./types/ApiResponseTypes.js";
 
 export class ResetPasswordApiClient extends BaseApiClient {
+    private readonly capabilities?: string;
+
+    constructor(
+        customAuthApiBaseUrl: string,
+        clientId: string,
+        httpClient: IHttpClient,
+        capabilities?: string
+    ) {
+        super(customAuthApiBaseUrl, clientId, httpClient);
+        this.capabilities = capabilities;
+    }
+
     /**
      * Start the password reset flow
      */
@@ -38,6 +51,9 @@ export class ResetPasswordApiClient extends BaseApiClient {
             {
                 challenge_type: params.challenge_type,
                 username: params.username,
+                ...(this.capabilities && {
+                    capabilities: this.capabilities,
+                }),
             },
             params.telemetryManager,
             params.correlationId

lib/msal-browser/src/custom_auth/core/network_client/custom_auth_api/SignInApiClient.ts

@@ -7,6 +7,7 @@ import { ServerTelemetryManager } from "@azure/msal-common/browser";
 import { GrantType } from "../../../CustomAuthConstants.js";
 import { CustomAuthApiError } from "../../error/CustomAuthApiError.js";
 import { BaseApiClient } from "./BaseApiClient.js";
+import { IHttpClient } from "../http_client/IHttpClient.js";
 import * as CustomAuthApiEndpoint from "./CustomAuthApiEndpoint.js";
 import * as CustomAuthApiErrorCode from "./types/ApiErrorCodes.js";
 import {
@@ -23,6 +24,18 @@ import {
 } from "./types/ApiResponseTypes.js";
 
 export class SignInApiClient extends BaseApiClient {
+    private readonly capabilities?: string;
+
+    constructor(
+        customAuthApiBaseUrl: string,
+        clientId: string,
+        httpClient: IHttpClient,
+        capabilities?: string
+    ) {
+        super(customAuthApiBaseUrl, clientId, httpClient);
+        this.capabilities = capabilities;
+    }
+
     /**
      * Initiates the sign-in flow
      * @param username User's email
@@ -36,6 +49,9 @@ export class SignInApiClient extends BaseApiClient {
             {
                 username: params.username,
                 challenge_type: params.challenge_type,
+                ...(this.capabilities && {
+                    capabilities: this.capabilities,
+                }),
             },
             params.telemetryManager,
             params.correlationId

lib/msal-browser/src/custom_auth/core/network_client/custom_auth_api/SignupApiClient.ts

@@ -5,6 +5,7 @@
 
 import { GrantType } from "../../../CustomAuthConstants.js";
 import { BaseApiClient } from "./BaseApiClient.js";
+import { IHttpClient } from "../http_client/IHttpClient.js";
 import * as CustomAuthApiEndpoint from "./CustomAuthApiEndpoint.js";
 import {
     SignUpChallengeRequest,
@@ -20,6 +21,18 @@ import {
 } from "./types/ApiResponseTypes.js";
 
 export class SignupApiClient extends BaseApiClient {
+    private readonly capabilities?: string;
+
+    constructor(
+        customAuthApiBaseUrl: string,
+        clientId: string,
+        httpClient: IHttpClient,
+        capabilities?: string
+    ) {
+        super(customAuthApiBaseUrl, clientId, httpClient);
+        this.capabilities = capabilities;
+    }
+
     /**
      * Start the sign-up flow
      */
@@ -33,6 +46,9 @@ export class SignupApiClient extends BaseApiClient {
                     attributes: JSON.stringify(params.attributes),
                 }),
                 challenge_type: params.challenge_type,
+                ...(this.capabilities && {
+                    capabilities: this.capabilities,
+                }),
             },
             params.telemetryManager,
             params.correlationId