Add native auth feature to support the external ID authentication (sign-in, sign-up and SSPR) (#7599)

CODEOWNERS

@@ -6,6 +6,7 @@
 
 # MSAL Browser
 /lib/msal-browser/ @sameerag @tnorling @hectormmg @jo-arroyo @peterzenz @konstantin-msft @lalimasharda @shylasummers
+/lib/msal-browser/custom-auth @shenj @yongdiw
 /samples/msal-browser-samples/ @sameerag @tnorling @hectormmg @jo-arroyo @peterzenz @konstantin-msft @lalimasharda @shylasummers
 
 # MSAL Common

README.md

@@ -18,6 +18,13 @@ The [`lib`](https://github.com/AzureAD/microsoft-authentication-library-for-js/t
     -   [On-behalf-of Flow](https://learn.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow)
 
 -   [Microsoft Authentication Library for JavaScript](lib/msal-browser/): A browser-based, framework-agnostic browser library that enables authentication and token acquisition with the Microsoft Identity platform in JavaScript applications. Implements the OAuth 2.0 [Authorization Code Flow with PKCE](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-auth-code-flow), and is [OpenID-compliant](https://docs.microsoft.com/azure/active-directory/develop/v2-protocols-oidc).
+
+-   [Native Authentication Support for JavaScript](lib/msal-browser/src/custom_auth/): MSAL also provides native authentication APIs that allow applications to implement a native experience with end-to-end customizable flows in their applications. With native authentication, users are guided through a rich, native, sign-up and sign-in journey without leaving the app. The native authentication feature is available for SPAs on [External ID for customers](https://learn.microsoft.com/en-us/entra/identity-platform/concept-native-authentication). It is recommended to always use the most up-to-date version of the SDK.
+
+    > **Note:** The native authentication feature is currently in preview and is not considered production-stable. Features and APIs may change before general availability.
+    >
+    > **Terminology:** In the codebase, the term "Custom Auth" is used instead of "Native Auth". You will find classes, interfaces, and configuration options prefixed with `CustomAuth` (e.g., `CustomAuthPublicClientApplication`, `CustomAuthConfiguration`). Please refer to these when implementing or exploring the native authentication feature in the code.
+
 -   [Microsoft Authentication Library for React](lib/msal-react/): A wrapper of the msal-browser library for apps using React.
 -   [Microsoft Authentication Library for Angular](lib/msal-angular/): A wrapper of the msal-browser library for apps using Angular framework.
 -   [Microsoft Authentication Extensions for Node](extensions/msal-node-extensions/): The Microsoft Authentication Extensions for Node offers secure mechanisms for client applications to perform cross-platform token cache serialization and persistence. It gives additional support to the Microsoft Authentication Library for Node (MSAL).

change/@azure-msal-browser-3240f33d-ab3b-4b05-9d0f-816c70517f13.json

@@ -0,0 +1,7 @@
+{
+  "type": "minor",
+  "comment": "Add native authentication feaetures for the external ID",
+  "packageName": "@azure/msal-browser",
+  "email": "shen.jian@live.com",
+  "dependentChangeType": "patch"
+}

docs/errors.md

@@ -751,6 +751,102 @@ msalInstance.acquireTokenSilent(); // This will also no longer throw this error
 ### `unsupported_method`
 - This method is not supported in nested app environment.
 
+## Custom Authentication errors
+
+### HTTP errors
+
+#### `no_network_connectivity`
+- No network connectivity. Check your internet connection.
+
+#### `failed_send_request`
+- Failed to send HTTP request to the server.
+
+### Configuration errors
+
+#### `missing_configuration`
+- Required configuration is missing for the custom authentication flow.
+
+#### `invalid_authority`
+- The provided authority URL is invalid or not supported for custom authentication.
+
+#### `invalid_challenge_type`
+- The challenge type specified in the configuration is not supported.
+
+### URL parsing errors
+
+#### `invalid_url`
+- The provided URL could not be parsed or is malformed.
+
+### User account attribute errors
+
+#### `invalid_attribute`
+- One or more user account attributes provided are invalid or malformed.
+
+### API errors
+
+#### `continuation_token_missing`
+- The continuation token required for the next step in the authentication flow is missing.
+
+#### `invalid_response_body`
+- The response body from the authentication server is invalid or malformed.
+
+#### `empty_response`
+- The server returned an empty response when data was expected.
+
+#### `unsupported_challenge_type`
+- The challenge type provided is not supported.
+
+#### `access_token_missing`
+- The access token is missing from the authentication response.
+
+#### `id_token_missing`
+- The ID token is missing from the authentication response.
+
+#### `refresh_token_missing`
+- The refresh token is missing from the authentication response.
+
+#### `invalid_expires_in`
+- The token expiration time (expires_in) value is invalid.
+
+#### `invalid_token_type`
+- The token type returned by the server is not supported.
+
+#### `http_request_failed`
+- The HTTP request to the authentication server failed.
+
+#### `invalid_request`
+- The authentication request is malformed or contains invalid parameters.
+
+#### `user_not_found`
+- The specified user could not be found.
+
+#### `invalid_grant`
+- The authorization grant provided is invalid, expired, or revoked.
+
+#### `credential_required`
+- User credentials are required to complete the authentication flow.
+
+#### `attributes_required`
+- Additional user attributes are required to complete the authentication flow.
+
+#### `user_already_exists`
+- A user with the specified identifier already exists.
+
+#### `invalid_poll_status`
+- The polling status returned by the server is invalid.
+
+#### `password_change_failed`
+- The password change operation failed.
+
+#### `password_reset_timeout`
+- The password reset operation timed out.
+
+#### `client_info_missing`
+- Client information is missing from the authentication response.
+
+#### `expired_token`
+- The provided token has expired and cannot be used.
+
 ## Other
 
 Errors not thrown by MSAL, such as server or cache errors.

lib/msal-browser/package.json

@@ -27,6 +27,16 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "exports": {
+    "./custom-auth": {
+      "import": {
+        "types": "./dist/custom-auth-path/custom_auth/index.d.ts",
+        "default": "./dist/custom-auth-path/custom_auth/index.mjs"
+      },
+      "require": {
+        "types": "./lib/custom-auth-path/types/custom_auth/index.d.ts",
+        "default": "./lib/custom-auth-path/msal-custom-auth.cjs"
+      }
+    },
     ".": {
       "import": {
         "types": "./dist/index.d.ts",

lib/msal-browser/rollup.config.js

@@ -17,7 +17,7 @@ const fileHeader = `${libraryHeader}\n${useStrictHeader}`;
 
 export default [
     {
-        // for es build
+        // Main SDK - ES build
         input: "src/index.ts",
         output: {
             dir: "dist",
@@ -32,17 +32,16 @@ export default [
             moduleSideEffects: false,
             propertyReadSideEffects: false,
         },
-        external: [
-            "@azure/msal-common/browser"
-        ],
+        external: ["@azure/msal-common/browser"],
         plugins: [
             typescript({
                 typescript: require("typescript"),
                 tsconfig: "tsconfig.build.json",
-            })
+            }),
         ],
     },
     {
+        // Main SDK - CommonJS build
         input: "src/index.ts",
         output: [
             {
@@ -65,10 +64,11 @@ export default [
                 sourceMap: true,
                 compilerOptions: { outDir: "lib/types" },
             }),
-            createPackageJson({libPath: __dirname})
+            createPackageJson({ libPath: __dirname }),
         ],
     },
     {
+        // Main SDK - UMD build
         input: "src/index.ts",
         output: [
             {
@@ -90,12 +90,16 @@ export default [
                 typescript: require("typescript"),
                 tsconfig: "tsconfig.build.json",
                 sourceMap: true,
-                compilerOptions: { outDir: "lib/types", declaration: false, declarationMap: false },
+                compilerOptions: {
+                    outDir: "lib/types",
+                    declaration: false,
+                    declarationMap: false,
+                },
             }),
         ],
     },
     {
-        // Minified version of msal
+        // Main SDK - UMD minified build
         input: "src/index.ts",
         output: [
             {
@@ -117,7 +121,11 @@ export default [
                 typescript: require("typescript"),
                 tsconfig: "tsconfig.build.json",
                 sourceMap: false,
-                compilerOptions: { outDir: "lib/types", declaration: false, declarationMap: false },
+                compilerOptions: {
+                    outDir: "lib/types",
+                    declaration: false,
+                    declarationMap: false,
+                },
             }),
             terser({
                 output: {
@@ -126,4 +134,52 @@ export default [
             }),
         ],
     },
+    {
+        // Custom Auth - ES module build
+        input: "src/custom_auth/index.ts",
+        output: {
+            dir: "dist/custom-auth-path",
+            preserveModules: true,
+            preserveModulesRoot: "src",
+            format: "es",
+            entryFileNames: "[name].mjs",
+            banner: fileHeader,
+            sourcemap: true,
+        },
+        treeshake: {
+            moduleSideEffects: false,
+            propertyReadSideEffects: false,
+        },
+        external: ["@azure/msal-common/browser"],
+        plugins: [
+            typescript({
+                typescript: require("typescript"),
+                tsconfig: "tsconfig.custom-auth.build.json",
+            }),
+        ],
+    },
+    {
+        // Custom Auth - CommonJS build
+        input: "src/custom_auth/index.ts",
+        output: {
+            dir: "lib/custom-auth-path",
+            format: "cjs",
+            banner: fileHeader,
+            sourcemap: true,
+            entryFileNames: "msal-custom-auth.cjs",
+            inlineDynamicImports: true,
+        },
+        plugins: [
+            nodeResolve({
+                browser: true,
+                resolveOnly: ["@azure/msal-common", "tslib"],
+            }),
+            typescript({
+                typescript: require("typescript"),
+                tsconfig: "tsconfig.custom-auth.build.json",
+                sourceMap: true,
+                compilerOptions: { outDir: "lib/custom-auth-path/types" },
+            }),
+        ],
+    },
 ];

lib/msal-browser/src/custom_auth/CustomAuthActionInputs.ts

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { UserAccountAttributes } from "./UserAccountAttributes.js";
+
+export type CustomAuthActionInputs = {
+    correlationId?: string;
+};
+
+export type AccountRetrievalInputs = CustomAuthActionInputs;
+
+export type SignInInputs = CustomAuthActionInputs & {
+    username: string;
+    password?: string;
+    scopes?: Array<string>;
+};
+
+export type SignUpInputs = CustomAuthActionInputs & {
+    username: string;
+    password?: string;
+    attributes?: UserAccountAttributes;
+};
+
+export type ResetPasswordInputs = CustomAuthActionInputs & {
+    username: string;
+};
+
+export type AccessTokenRetrievalInputs = {
+    forceRefresh: boolean;
+    scopes?: Array<string>;
+};
+
+export type SignInWithContinuationTokenInputs = {
+    scopes?: Array<string>;
+};

lib/msal-browser/src/custom_auth/CustomAuthConstants.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Constants } from "@azure/msal-common/browser";
+import { version } from "../packageMetadata.js";
+
+export const GrantType = {
+    PASSWORD: "password",
+    OOB: "oob",
+    CONTINUATION_TOKEN: "continuation_token",
+    REDIRECT: "redirect",
+    ATTRIBUTES: "attributes",
+} as const;
+
+export const ChallengeType = {
+    PASSWORD: "password",
+    OOB: "oob",
+    REDIRECT: "redirect",
+} as const;
+
+export const DefaultScopes = [
+    Constants.OPENID_SCOPE,
+    Constants.PROFILE_SCOPE,
+    Constants.OFFLINE_ACCESS_SCOPE,
+] as const;
+
+export const HttpHeaderKeys = {
+    CONTENT_TYPE: "Content-Type",
+    X_MS_REQUEST_ID: "x-ms-request-id",
+} as const;
+
+export const DefaultPackageInfo = {
+    SKU: "msal.browser",
+    VERSION: version,
+    OS: "",
+    CPU: "",
+} as const;
+
+export const ResetPasswordPollStatus = {
+    IN_PROGRESS: "in_progress",
+    SUCCEEDED: "succeeded",
+    FAILED: "failed",
+    NOT_STARTED: "not_started",
+} as const;
+
+export const DefaultCustomAuthApiCodeLength = -1; // Default value indicating that the code length is not specified
+export const DefaultCustomAuthApiCodeResendIntervalInSec = 300; // seconds
+export const PasswordResetPollingTimeoutInMs = 300000; // milliseconds