Microsoft Entra External ID
Authentication

Authenticate an embedded webview from a native app

In brief

The article now describes using a resource access token to authenticate an embedded webview and establish the web resource’s session. Prerequisites now include an externally configured app, exposed delegated scopes, HTTPS, and server-side token validation.

What Entra admins need to know

Review app and web-resource configuration against the updated prerequisites, particularly delegated scopes and token validation.

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.

Implement single sign-onAuthenticate an embedded webview from a native apps to embedded web viewsapp

[!INCLUDE applies-to-external-only]

When[!INCLUDE applies-to-authentication-native]

Use a resource access token to open an authenticated web page inside your mobilenative app. This guide connects a user signed in through Microsoft Entra External ID to an HTTPS web resource your team controls, such as your app includes web-based features like a profile update page or's rewards dashboard, users expect a seamless single sign-on experience. They shouldn't encounterpage, without a second login prompt after already signing sign-in through the native app.prompt.

You need a native app with a working sign-in flow and a web resource that can validate bearer tokens. This article shows you how to implementresource-token flow provides single sign-on (SSO) betweento that resource in the embedded webview.

[!INCLUDE native-authentication-public-preview]

The resource-token pattern for embedded webviews is generally available. It establishes a session for your web resource, independently of the Native Authentication API's support contract.

Prerequisites

  • An app configured for Embedded native mobile application andauthentication in an external tenant. See Configure an application.
  • A native app with a working sign-in flow. See the sign-in reference.
  • An HTTPS web resource hosted in an embedded web view (for example, WKWebView on iOS or WebView on Android)with exposed delegated scopes and server-side token validation. See Expose a web API. Unlike system browsers, embedded web views allow you to manipulate network requests before they're sent. This capability enables your
  • Permission for the native app to injectrequest those scopes. See Configure access to your web API.
  • An embedded webview that can send an Authorization header with its initial request.

Sign in with native authentication

Request access for the user's authentication state directly into request headers.

The recommended flow works as follows:resource you intend to open, rather than reusing a token issued for a different API.

  1. The user signs in through the mobile app's native UI using the Native Auth SDK or the native authentication API.
  2. Before loadingStart authorization with the web view,resource's required scopes in the app retrieves a valid accessinitial scope parameter. Request only the permissions needed for the page's operations.
  3. Complete the sign-in actions returned by the service. Follow the returned links and use the latest continuation token fromfor the SDK or API.active transaction.
  4. The app loadsWhen the service returns state: continue, follow _links.continue to resume authorization.
  5. Exchange the returned authorization code for tokens. Use the response's access_token for the web view withresource, not the id_token or a customcontinuation token.

For the authorization and token request that includescontracts, see the access token inNative Authentication API reference.

For existing V1 integrations, see the Authorization: Bearer <access_token> header.

  • The web resource validates the tokenV1 API reference and grants access immediately.
  • its SDK library references for your platform.

    The following diagram showsillustrates the interaction between the web resource, mobile app, SDK, and the identity service (ESTS):resource-token flow with a V1 SDK:

    :::image type="content" source="./media/native-authentication/common/native-application-sign-in-with-web-view-authentication.png" alt-text="Sequence diagram showing an app signing in through an SDK and sending an access token in the SSO flow whereembedded webview request.":::

    Retrieve the mobile app signs in via SDK, receives tokens, and loadsaccess token

    Before opening the web view withwebview, get a valid, unexpired access token for the resource.

    1. Check the token response's expiration metadata rather than parsing the access token in the Authorization header.":::

      Prerequisites

      Sign in with native authentication

      Complete the standard sign-in flow using the Native Auth SDK or the native authentication API. When sign-in succeeds using the SDK, it caches the access token, ID token, and refresh token securely. If you use the API directly, your app is responsible for securely storing the tokens it receives.

      For detailed sign-in implementation steps, see:

      Retrieve the access token

      When the user triggers the action to open the web view, ensure the app hasdoesn't have a valid, unexpired accessusable token for the required resource and scopes, complete authorization to obtain one before loading the web resource.page.

    2. Keep the token in the native app's protected authentication state until you construct the request. Don't expose it in page scripts, diagnostics, or a URL.

    Access tokens are validated by the receiving resource, not by the native client. See Access tokens.

    If youFor V1 SDK token acquisition, use the Native Auth SDK, request a token silently. The SDK provides a getAccessToken() method that retrieves a valid token from the cache or silently refreshes it. For details on acquiring access tokens with specific scopes, see:

    If you use the native authentication API directly, your app retrieves tokens through the APIplatform's /oauth/v2.0/token endpoint. For details, see Native authentication API referenceSDK library reference.

    Request the token with the exact scopes required by the web resource. For scope requirements, seedescribed in Limitations and configuration requirements.

    Load the web view with authentication

    There are two methods to passSend the authentication statetoken in the initial request to the intended web view. The recommended approach uses authorization headers. A cookie-based fallback is available for legacy scenarios but is discouraged.

    Option A: Use a bearer token via HTTP header (recommended)

    Inject the access token directly into the Authorization header of the initial HTTP request used to loadresource. This procedure establishes the web view. This is the most secure and robust method.resource's session.

    This approach is preferred because it:

    • Is stateless: It doesn't rely on persistent cookies on the client side.
    • Isolates the token: It strictly limits the token to this specific request flow.
    • Avoids web-based attack vectors: It sidesteps common security issues associated with browser-managed sessions.

    To load the web view with header-based authentication:

    1. Construct the HTTPS URL for your web resource without including the token in its path, query, or fragment.
    2. Create the initial webview request with Authorization: Bearer <access-token>, replacing <access-token> with the access token for the web resource. Ensure it uses HTTPS.
    3. Create a custom networkLoad that request object.in the embedded webview.
    4. AddRestrict bearer-token delivery to the intended resource. Don't forward the header to unrelated origins when handling navigation or redirects.

    Use bearer authentication for the initial request and let the server issue the application session cookie after validation. Keep the raw access token in the native app's protected authentication state.

    Validate and persist the token on the backend

    The web resource validates the access token and authorizes the requested operation before creating a session.

    Validate the token

    Use the resource's token-validation middleware before returning protected content.

    1. Validate the token's signature, issuer, and lifetime against the resource's trusted Microsoft Entra configuration.
    2. Verify that the Authorization: Bearer <access_token>aud claim identifies the receiving resource.
    3. Verify the delegated scopes required for the requested operation and the user's authorization to access the data.
    4. Reject the request if validation or authorization fails. Don't create a session from an invalid token.

    For the audience and permission checks, see Validate access-token claims.

    Persist the session

    Establish a server-managed session for subsequent webview navigation.

    1. After successful token validation, issue the web resource's session cookie through Set-Cookie.
    2. Set HttpOnly, Secure, and the SameSite policy appropriate for the application's navigation. Apply server-side protection against cross-site request forgery for cookie-authenticated operations.
    3. Use the session cookie for subsequent requests to that web resource. Don't store the raw access token in the cookie.

    Verify access and sign-out

    Signing out of the native app doesn't terminate the web resource's session or other application and browser sessions. Clear each session through its own sign-out mechanism.

    Test both resource authorization and the session that the webview retains.

    1. Sign in to the request.
    2. Load the request intonative app and open the web view component (for example, WKWebView on iOS or WebView on Android).resource. Confirm that the expected user's page opens without another sign-in prompt.
    3. Navigate to another protected page in the same web resource. Confirm that its server-issued session cookie maintains the session.
    4. Test an expired token, a token issued for a different resource, and a token without the required scope. Confirm that none establishes an authorized session.
    5. Sign out and clear authentication state in both the native app and the web resource. Reopen the protected page and confirm that the old web session no longer grants access.
    6. Check that application and server diagnostics exclude tokens, cookies, credentials, and personal data.

    Option B: Use cookies (fallback only)

    Limitations and configuration requirements

    IfThe token's audience and permissions identify the target web resource can't handle header-based authentication (for example, certain legacy single-page applications), youand authorized operations. The native client and resource can inject the token as a cookie. This approach is generally discouraged because of security risks.have separate app registrations.

    Injecting cookies into a web view entrusts the authentication state to a browser-managed mechanism. This makes the session "ambient" (automatically attached to requests), which exposes the app to standard web attack classes:

    • XSS (cross-site scripting): The session is vulnerable to hijacking ifintegration requires control over the web resource's bearer-token validation and session creation.

      The resulting cookie belongs to your web resource. It doesn't create a browser-wide Microsoft Entra session or enable profile or credential-management APIs.

      Related content is compromised.

      If you use the cookie-based approach, these requirements apply:

      • Use server-issued session cookies where possible.
      • Avoid placing raw access tokens directly into cookies.
      • Set cookies with the HttpOnly, Secure, and appropriate SameSite attributes.
      • Enforce strict CSRF protection on the server side.

      Validate and persist the token on the backend

      When the request reaches the web resource, the backend processes the token to establish the session.

      Validate the token

      The web server intercepts incoming requests and verifies the token's signature and claims. For ASP.NET Core backends, use Microsoft.Identity.Web (MISE) to handle validation automatically.

      Ensure the token's audience (aud) claim matches the web API's identifier and the issuer (iss) claim matches the expected authority.

      Persist the session

      The web view doesn't persist custom headers on subsequent navigation events (for example, when the user selects a link). To maintain the authenticated state after the initial request, the server issues a standard session cookie (Set-Cookie) upon successful validation of the initial bearer token.

      Configure the session cookie with the following attributes:

      • HttpOnly
      • Secure
      • An appropriate SameSite policy

      Limitations and configuration requirements

      To ensure the token issued to the mobile app is accepted by the web resource, keep the following configurations in mind:

      • Shared client identity: The mobile app and web app should share the same client ID (application ID). If they have different IDs, the backend rejects the mobile app's token as an audience mismatch.
      • Scope alignment: The mobile app requests the access token with the exact scopes required by the web resource (for example, Profile.Read, Orders.Write).

      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…