Today we announce that Native Authentication JavaScript SDK for Microsoft Entra External ID is now Generally Available! Initially released in 2024, Native Authentication empowers developers to build sign-in, sign-up and sign-out experiences for single page applications (SPAs) in Entra External ID.

How to use native authentication JavaScript SDK

You can add native authentication to your single page applications (SPAs) by using the Microsoft Authentication Library (MSAL) for JavaScript with the native authentication extensions. Whenever possible, use MSAL to integrate native authentication for SPA experiences. If you’re targeting platforms not supported by MSAL, use the underlying authentication APIs directly.

Install MSAL SDK and Import Native Authentication Extension

npm i @azure/msal-browser

MSAL abstracts the protocol and exposes simple, scenario-based APIs. For example, to sign a user in using an email one-time passcode (OTP) flow, your app starts the sign-in with the user’s email. MSAL drives the next step by returning a state indicating that a code is required; you then collect the OTP and submit it to complete sign-in.

Below is a JavaScript/TypeScript example that signs a user in using the email OTP flow. The signIn method returns a result that contains a state object. That state can represent different steps (for example, “code required”, “password required”, “complete”, or “failed”). Your code inspects the state and proceeds accordingly.

Sign In with Email One-Time Passcode (OTP)

import { 
 CustomAuthPublicClientApplication, 
 SignInCompletedState, 
 SignInCodeRequiredState, 
 SignInPasswordRequiredState, 
 AuthFlowStateBase, 
 ICustomAuthPublicClientApplication, 
} from "@azure/msal-browser/custom-auth"; 
// Create the client 
const authClient: ICustomAuthPublicClientApplication = 
await CustomAuthPublicClientApplication.create(customAuthConfig); 
// Start sign-in with the user's email (username) 
const actionResult = await authClient.signIn({ username: emailAddress }); 
// Inspect the result state and proceed 
if (actionResult.isCodeRequired()) { 
// Next step: prompt user for the OTP code (e.g., via a form) 
 const submitCodeResult = await actionResult.state.submitCode(code); 
 if (submitCodeResult.isCompleted()) { 
// Handle sign-in success 
 const accountData = submitCodeResult.data; // CustomAuthAccountData 
  } 
}  

Handling Common Error Scenarios

Map well-known errors to user-friendly messages and remediation steps:

const result = await authClient.signIn({ username: emailAddress }); 
if (result.isFailed()) { 
  const err = result.error; 
  if (err?.isUserNotFound()) { 
    // User not found 
  } else if (err?.isInvalidUsername()) { 
    // Invalid email/username 
  } else if (err?.isInvalidCode()) { 
    // Code incorrect (if code was required earlier) 
  } else if (err?.isRedirectRequired()) { 
    // Fallback to delegated (web-based) sign-in when native cannot proceed 
  } else { 
    // Generic error 
    // err?.errorData?.errorDescription 
  } 
} 

Ready to get started?

Stay connected and informed

To learn more or test out features in the Microsoft Entra suite of products, visit our developer center. Make sure you subscribe to the Identity blog for more insights and to keep up with the latest on all things Identity. And, follow us on YouTube for video overviews, tutorials, and deep dives.