Microsoft Entra ID
Authentication

Embedded native authentication web fallback overview

In brief

The page explains that unsupported native interactions can start a separately configured browser sign-in, which restarts authentication rather than resuming the native transaction. It adds handling guidance for redirects, OAuth web-redirection errors, unknown required actions, and sign-in completion.

What Entra admins need to know

Review apps using native authentication to ensure browser fallback is integrated separately, tokens are not placed in browser URLs, and users are not marked signed in before browser authentication succeeds.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

NativeEmbedded native authentication web fallback overview

[!INCLUDE applies-to-external-only]

Web fallback allows a client app that uses[!INCLUDE applies-to-authentication-native]

An Embedded native authentication interaction can require behavior that your app can't complete natively. Browser fallback is a recovery path that starts a separate, configured browser sign-in. It doesn't resume the native transaction.

[!INCLUDE native-authentication-public-preview]

Service-required and client-initiated fallback

The API uses states, actions, and links to describe the next interaction. A client can present available actions or apply application flow logic to select an allowed operation.

The Native Authentication API can return the following response:

{
    "state": "redirect"
}

This response can contain only state. It doesn't supply a continuation token or a browser handoff URL. Stop the native transaction instead of requiring action, continuationToken, or _links on this response.

At the OAuth boundary, browser-required handling can instead useinvalid_grant with web_redirect_required. Handle that OAuth error separately from native JSON states.

A client can also reach a response it can't safely process: an unknown required action, a missing required field, an unsupported credential interaction, or malformed data. Offer a separately configured browser sign-in if your app has one, or show a clear failure without marking the user signed in.

Unknown optional properties or links are different. Ignore those additions while processing the required fields; their presence alone doesn't require a switch to the browser.

Transaction and user-experience boundaries

A separate browser sign-in restarts authentication; it doesn't preserve native progress.

Native continuation tokens belong to the active transaction and current operation. They aren't general-purpose browser sign-in tokens. Don't add passwords, one-time passcodes (OTPs), native continuation tokens, or security tokens to browser URLs. Let the configured authorization flow handle its registered redirect. Keep authorization codes and other credentials out of logs and telemetry. Use the configured interactive authorization flow, not an arbitrary URL supplied by untrusted content.

The browser flow can have different interactions from the native flow. Don't mark the app signed in until its configured authentication integration reports success. If the user cancels or the browser flow fails, retain a clear signed-out or incomplete state.

Browser integration

Use a supported browser-delegated authentication as a fallback mechanismintegration to improve resilience. This scenario happens whenopen the browser and handle its registered redirect. The mobile quickstart and single-page app quickstart describe those integration paths. Keep browser completion, cancellation, and error handling separate from native authenticationtransaction processing.

For an application configured with Bring Your Own UX (BYO UX), normal browser authorization uses the configured self-hosted page. A native redirect response isn't sufficienta URL or parameter for bypassing that configuration to completeMicrosoft-hosted pages. Use the authentication flow. For example, if theconfigured browser authorization server requires capabilitiesflow rather than a constructed bypass URL.

If your app doesn't have a supported browser path, explain that the clientinteraction can't provide.be completed. Don't automatically replay credentials or switch the active transaction to V1.

V1 fallback

All client apps that use native authentications needsV1 clients need to support web fallback.

Web fallback flow

This flow shows how web fallback can happen:

  • The client app collects initial information fromdeclares its supported interactions through challenge types. For example, an email-with-password user flow requires both oob and password; omitting either can cause the user andservice to require browser authentication. See V1 challenge types.

    For existing SDK integrations, use the SDK library references for fallback interfaces. V1 fallback starts the authentication flow by making a request to Microsoft Entra.

  • Microsoft Entra returnsseparate browser sign-in, not a success or error response. A success response indicates the client app can continue making requests Microsoft Entra. An error response can indicate the client can continue to prompt the user for more information and continue to make requests to Microsoft Entra. The error response can also indicate the client needs to use browser-delegated authentication.
  • If the error response indicates the client needs to use browser-delegated authentication, the client continues the authentication flow in the browser.

Example scenario

Let's look at an example when it's possible for Microsoft Entra to indicate that the client needs to use browser-delegated authentication:resumable native-to-browser continuation.

  • In the Microsoft Entra admin center, an administrator configures an app to use email with password authentication method.
  • This configuration means Microsoft Entra requires the client app to have the ability to collect an email (username) and password from user. The client app communicates this ability to Microsoft Entra by sending password challenge type. Learn more about challenge types in Native authentication challenge types article.
  • The client app should also validate the email by submitting a one-time passcode that the server sends to the user's email. The client app communicates this ability to Microsoft Entra by sending oob challenge type. Learn more about challenge types in Native authentication challenge types article
  • If the client app doesn't send both oob and password challenge types, Microsoft Entra interprets it as the client app's inability to fulfill the set requirement. In this case, Microsoft Entra returns an error that indicates the client needs to use browser-delegated authentication.

Support web fallback

If Microsoft Entra's response indicates that the client app needs to fall back to the browser-delegated authentication, we recommend you use a Microsoft-built and supported authentication library.

Learn how to support web fallback in the following apps when you use native authentication:

Related content

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…