Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Applies to:
External tenants (learn more)
Authentication approach: Embedded native authentication.
Configure your application registration and user flow before calling the Native Authentication API. This guide prepares a public client application for Embedded native authentication through direct API calls or an SDK.
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.
Prerequisites
- An external tenant.
- An account authorized to create or manage the application registration.
- Access to create or select the user flow and associate the application with it. Coordinate policy changes and consent with the appropriate tenant administrator.
- A tenant-verified custom URL domain configured for the authentication service.
An application owner can manage the registration's authentication settings. For delegated access, use application-scoped permissions rather than assigning a tenant-wide administrator role solely for this task.
Register the application
Create the registration in the external tenant that owns the customer accounts.
- Sign in to the Microsoft Entra admin center and switch to your external tenant.
- Browse to Entra ID > App registrations > New registration.
- Enter an application Name and select the single-tenant supported account type for your external tenant.
- Select Register.
- On Overview, record the Application (client) ID and Directory (tenant) ID.
- Record the tenant subdomain if your selected SDK requires it. Configure service API URLs with your tenant-verified custom domain as described in Configure the API authority.
For registration details, see Register an application. The client ID identifies this public client; it isn't a secret. Don't create or embed a client secret for these direct API requests.
Configure the API authority
Use your tenant-verified custom domain for all service API calls in the current native authentication integration. The authority has the form https://{custom_domain}/{tenant}, where custom_domain is the verified authentication domain, such as login.contoso.com, and tenant is the Directory (tenant) ID, a GUID.
- Verify and configure the custom URL domain in the external tenant.
- Configure the application or SDK to use that domain for authorization challenges, native interaction operations, authorization continuation, and token exchange.
- Validate returned links against the configured authority. Keep their paths, versions, and query parameters unchanged.
For SPAs with Embedded native authentication and BYO UX websites, configure a cross-origin resource sharing (CORS) proxy or edge policy for cross-origin browser API calls. A proxy address is a transport setting, not a replacement service authority. Its upstream calls still use the tenant-verified custom domain and tenant GUID. See the provider-neutral proxy requirements.
Android and iOS apps using native HTTP transports call the service authority directly. They don't need CORS configuration or a CORS proxy.
Enable public client and native authentication flows
The API requires native authentication to be enabled on this application.
- In the app registration, under Manage, select Authentication.
- On Redirect URI configuration, set Enable the following mobile and desktop flows to Yes.
- Set Enable native authentication to Yes.
- Select Save.
These application settings enable the integration. The app then uses returned methods, actions, and links to select allowed operations through user choice or application flow logic.
Configure redirect URIs separately for any platform SDK or browser-delegated integration you use. Browser sign-in needs its registered callback and the platform's URL-scheme or manifest configuration. Direct native authorization-code redemption doesn't establish a browser session and isn't a reason to require a browser redirect URI on every direct HTTP client.
See Redirect URI configuration for browser and platform registration requirements.
Choose an integration
Choose direct API calls or Microsoft Authentication Library (MSAL) entry points for your platform. For direct calls, native routes use /api/v2.0 and OAuth routes use /oauth2/v2.0; follow the API reference.
Use the SDK compatibility guidance for the documented package versions, entry points, and enrollment support. Installing a new package doesn't migrate V1 calls. Keep V1 and V2 continuation states separate.
For direct inline email and SMS method registration, use the enrollment contract.
Create and associate a user flow
The associated user flow determines the email sign-up/sign-in method and requested attributes. Tenant and user-flow policies apply to Microsoft-hosted authentication, Embedded native authentication, and Bring Your Own UX (BYO UX). Use the shared method and journey matrix to check which interactions each approach supports.
- Browse to Entra ID > External Identities > User flows.
- Select New user flow, or open the existing user flow you intend to use.
- For a new flow, enter a Name. Under Identity providers, select Email Accounts and choose Email with password or Email one-time passcode.
- Under User attributes, choose the attributes your application needs to collect. For a first integration, keep the required profile fields to the minimum your application needs.
- Select Create for the new flow.
- Open the flow. Under Use, select Applications > Add application.
- Select the app registration, then choose Select.
An application has one user flow; a user flow can serve multiple applications. For an existing flow, verify the selected identity provider and attributes before changing settings used by other applications.
If you select email one-time passcode, enable it at the tenant level as described in Create a user flow. The sign-up API doesn't have a parameter that overrides the user flow's method selection.
Configure scopes and consent
Establish permissions before starting authorization.
- Identify the target resource and delegated scopes your application needs. The authorization request's
scopeparameter establishes the requested access. - If the app calls a protected API, configure its delegated permission on the client registration and arrange consent from an administrator authorized for that permission.
- In API permissions, inspect the requested permissions and consent status. Don't add broad Microsoft Graph permissions just to enable native authentication.
- Request the selected scopes in the initial authorization challenge. Add
offline_accessonly if your app needs a refresh token.
The tenant's permissions and consent requirements apply to the target resource. See Add permissions to access your web API.
Prepare MFA and password reset
Configure multifactor authentication (MFA) through the tenant's authentication-method and Conditional Access policies. The service enforces these requirements; the client handles the returned authentication steps.
- If your application uses password accounts, enable self-service password reset for the intended customers and recovery methods.
- Configure the MFA requirements for the application and customers.
- Prepare a customer account with the methods needed by the policy. Verify its recovery methods before testing password reset.
- Test a flow with additional authentication required. Continue processing returned actions after sign-up or password reset rather than treating either operation as final authorization.
Inline method registration has a separate contract from profile attribute collection. The flow concept links to the enrollment and activation contract.
Verify the configuration
Use the request and response contracts in the API reference for a direct integration, or run the SDK quickstart with the React Next.js sample. Validate the selected integration with your application and user flow.
- Start authorization. An unauthenticated request normally returns
401 InsufficientAuthorizationwith a continuation token and enabled journey links. - Confirm that the intended journey link is present. If it isn't, check the app's user-flow association and policy configuration instead of constructing a missing URL.
- Complete an advertised method, resume authorization, and exchange the code.
| Symptom | Configuration to check |
|---|---|
invalid_client |
Tenant/client ID match and native authentication enabled for the selected app. |
invalid_scope |
Scope spelling, resource registration, configured permissions, and consent. |
| No expected journey link | User-flow association and enabled authentication/recovery options. |
| Browser preflight failure | The proxy's allowed browser origin, OPTIONS handling, headers, JSON POST, and PUT. The service answers OPTIONS but doesn't grant browser-origin access. |
| Browser callback failure | The redirect URI and platform configuration for that browser integration, separately from direct native code redemption. |