Notă
Accesul la această pagină necesită autorizare. Puteți încerca să vă conectați sau să modificați directoarele.
Accesul la această pagină necesită autorizare. Puteți încerca să modificați directoarele.
Applies to:
External tenants (learn more)
Authentication approach: Embedded native authentication.
Embedded native authentication is an authentication approach that lets your application present sign-up, sign-in, and password reset while Microsoft Entra External ID validates credentials and enforces authentication requirements. Your app controls the interface and handles the actions, available methods, and links returned by the Native Authentication API.
API version boundaries
Important
The Native Authentication API V2 is in preview. The Native Authentication API V1 remains generally available. See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to preview features.
The primary references describe the response-driven Native Authentication API, with native routes such as /api/v2.0. Follow service-returned links without rewriting their versions or paths. The /oauth2/v2.0 OAuth endpoint path is also used by V1 integrations.
Existing V1 integrations can continue to use the V1 API reference and its SDK library references. The legacy V1 guides and tutorials have been removed from this documentation. This documentation change doesn't announce retirement of V1 or its SDKs. See SDK compatibility and migration for platform and package requirements.
Application-owned experience, service-controlled authentication
With Embedded native authentication, a mobile, desktop, or single-page application (SPA) can present authentication within its own interface. Your application controls layout, interaction, and validation feedback. Microsoft Entra External ID validates credentials, enforces authentication requirements, and issues tokens.
Tenant and Conditional Access policies and the application's user flow apply to Microsoft-hosted authentication, Embedded native authentication, and Bring Your Own UX (BYO UX). Presentation and integration responsibilities differ. With Embedded native authentication, your app handles the required interactions, such as a second-factor challenge after password verification or more attribute collection after email verification.
Microsoft-hosted authentication presents pages on behalf of your app. Choose Embedded native authentication when your team needs control of the interface and can implement response handling and security responsibilities. See Choose an authentication approach for the broader comparison.
Customer journeys
The same authorization transaction surrounds each journey. Your app starts authorization, completes the returned authentication interactions, resumes authorization, and exchanges the authorization code for tokens.
| Journey | Behavior |
|---|---|
| Sign-up | Create an email-with-password or passwordless email one-time passcode (OTP) account. Collect the attributes and complete the verification steps requested by the user flow. |
| Sign-in | Submit the customer's identifier and complete password or email one-time-passcode verification using an offered method. Username-with-password sign-in is also available for configured local accounts. |
| Password reset | Verify an offered email or SMS one-time passcode, submit a replacement password, and follow the password-update polling responses. Recovery can start before sign-in discovery or through a password method's recover link. |
| Multifactor authentication (MFA) and inline registration | Complete email or SMS verification when policy requires MFA. If registration is required, handle the returned enroll and activate operations. Email OTP first-factor accounts use a different second factor, such as SMS. |
| Policy requirements after sign-up or password reset | Continue handling required authentication, including MFA and Conditional Access, before requesting tokens. Completing account creation or a password update doesn't bypass policy. |
Select journeys and methods from those available in the current transaction. Your application can present a choice or apply its flow logic within those options.
The Native Authentication API doesn't support federation, phone numbers as a first factor, time-based one-time passwords (TOTP), passkeys, push authentication, or external MFA methods. Later-operation step-up and using native-issued tokens with profile or credential-management APIs aren't supported. See the method and integration matrices for the comparison with Microsoft-hosted authentication and BYO UX.
For supported custom authentication extension events, see the approach comparison. For configuration, see Custom authentication extensions.
Integration responsibilities
Use the configuration guide and API references for a direct integration, or use a documented JavaScript, Android, or Apple SDK. The SDK quickstart configures a React Next.js sample. SDK entry points and supported continuation interfaces are specific to the package and platform.
| Responsibility | What your application implements |
|---|---|
| Response handling | Use the latest state, action, and links to select an allowed operation through user choice or application flow logic. |
| Method selection | Select from the returned methods, use masked hints where needed, and follow the selected method's links. |
| Attribute collection | Collect values according to the returned field requirements and validation metadata. Don't require page-grouping metadata. |
| Transaction continuity | Keep the latest continuation token in memory and use it only with links from the same response. |
| Authorization | Request the needed scopes initially and exchange the final authorization code for tokens. |
| Recovery | Handle validation failures, throttling, expiration, unsupported interactions, and cancellation without replaying credentials automatically. A separately configured browser sign-in starts a new authentication attempt; it doesn't resume native progress. |
SPAs with Embedded native authentication and BYO UX websites need a proxy or edge cross-origin resource sharing (CORS) policy for cross-origin browser API calls. Android and iOS apps using native HTTP transports don't need CORS or a CORS proxy. See Native authentication CORS concepts.
The Native Authentication API V2 requires a tenant-verified custom domain for browser-based apps, such as SPAs, to help protect against cross-site request forgery (CSRF). Non-browser clients, such as Android and iOS apps using native HTTP transports, don't require a custom domain. An embedded browser or webview isn't a native HTTP transport. BYO UX websites still require a tenant-verified custom domain. Configure the service authority before starting a journey; see Configure the API authority.
Security boundaries
Your application handles credentials, so protect passwords, one-time passcodes, continuation tokens, authorization codes, and issued tokens. Use HTTPS, don't log authentication bodies, and don't cache credential responses. Validate returned URL authorities before sending transaction data.
Use client-side validation to help customers correct their input. The service validates authentication requests.
Session boundaries
Embedded native authentication supports single sign-on (SSO) for embedded webviews. A signed-in native app requests an access token for the web resource and includes it in the webview request's Authorization header. The resource validates the token and establishes a session, allowing access without another sign-in prompt. See Authenticate an embedded webview from a native app.
Signing out of your native app doesn't terminate other application or browser sessions. Clear each application's session separately when your sign-out experience requires it.
Existing V1 application configuration
For existing V1 applications, enable public client and native authentication flows, then update your platform configuration. The V1 API reference describes challenge types and capabilities. For a response-driven integration, follow Configure an application to select and configure the V2 entry points.
Conditional Access and sign-in frequency
Microsoft Entra External ID supports the Conditional Access sign-in frequency (SIF) session control for both Microsoft-hosted and native authentication.
For native authentication, when reauthentication is required by the policy, Microsoft Entra External ID prevents token issuance during refresh token grants (grant_type=refresh_token). Your app must handle the failed token refresh and prompt the user to sign in again before it can acquire new tokens. The policy doesn't display the sign-in UI for your app.
Next steps
- Run the SDK sign-in quickstart.
- Configure an application for native authentication.
- Implement the Native Authentication API.
- Review SDK compatibility and migration.