Microsoft Entra ID
Authentication

Migrate Embedded native authentication from V1 to V2

In brief

The documentation now requires tenant-verified custom domains for browser-based apps, while native Android and iOS clients can use their configured service authority without one or a CORS proxy. The listed MSAL.js minimum version is now 5.29.1.

What Entra admins need to know

Verify browser apps use a verified custom domain consistently across the documented flows, and update JavaScript clients to MSAL.js 5.29.1 or later.

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.

title: Migrate Embedded native authentication from V1 to V2 description: Update a V1 integration for response-driven Embedded native authentication, including SDK interfaces, authorization, attributes, errors, and tokens. ms.topic: how-to ms.date: 11/13/17/2026 ms.custom: msecd-doc-authoring-1030 ai-usage: ai-generated #customer intent: As an application developer, I want to migrate my V1 integration so that my app follows the V2 authentication contract.

Configure the service authority

UseThe Native Authentication API V2 requires a tenant-verified custom domain for every current API call, includingbrowser-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 remains browser-based and requires a tenant-verified custom domain.

If you use a custom domain, apply it consistently to OAuth authorization start, native operations, authorization continuation, and token redemption.redemption:

  1. Set the service authority to https://<tenant-verified-custom-domain>/<tenant-GUID>.

  2. Configure that custom-domain authority through the selected SDK's existing properties:

    • Android: Set authorities[0].type to CIAM and authorities[0].authority_url to the full service authority.
    • iOS and macOS: Create MSALCIAMAuthority with the full URL and pass it to MSALNativeAuthPublicClientApplicationConfig(clientId:authority:challengeTypes:). Don't use the tenantSubdomain convenience initializer, which constructs the default login host.
  3. For SDK browser calls, set the required customAuth.authApiProxyUrl string to the same full custom-domain authority and configure CORS at that edge. This route doesn't use an application proxy's local transport prefix. Apply the shared proxy contract for origins, preflight, SDK headers, and success and error responses.

  4. For direct HTTP integration, resolve relative returned links against the service authority. Before sending credentials or continuation tokens, reject an unexpected hostname or tenant path. If your browser integration uses proxy transport mapping, apply it only after validating the service destination.

CORS and proxy configuration apply to cross-origin browser calls from SPAs with Embedded native authentication and BYO UX websites. Android and iOS apps using native HTTP transports call thetheir configured service authority directly and don't need a CORS proxy. For these non-browser clients, retain the SDK's documented authority configuration if you don't use a custom domain. Validate returned links against the configured authority in either case.

SDK compatibility

Platform SDK and minimum version V2 interface
Android MSAL for AndroidMSAL for Android (com.microsoft.identity.client:msal) 8.7.0 or later. INativeAuthPublicClientApplication.signInV2, signUpV2, and resetPasswordV2; unified NativeAuthResultV2 results.
iOS and macOS MSAL for iOS and macOSMSAL for iOS and macOS releases 2.18.1 or later. MSALNativeAuthPublicClientApplication V2 entry points; scenario-specific parameter types, shared MSALNativeAuthFlowDelegate, and typed per-state delegates.
JavaScript and TypeScript MSAL for JavaScriptMSAL for JavaScript releases (@azure/msal-browser) 5.29.01 or later. ICustomAuthPublicClientApplicationV2 with signInV2, signUpV2, and resetPasswordV2; use the matching V2 input, result, and state types.

Display only methods returned for the transaction. Use the shared method and journey matrix for service capabilities, then check the selected SDK implementation:

Keep the existing client factory, but replace V1 parameter objects with NativeAuthSignInParametersV2, NativeAuthSignUpParametersV2, and NativeAuthResetPasswordParametersV2. Pass them to signInV2, signUpV2, and resetPasswordV2. Select V2 through these entry points, not a configuration flag.

The Android sampleAndroid sample demonstrates V1 and V2 journeys.

  • Dispatch NativeAuthResultV2 after every entry point and continuation. Retain the returned nextState.
  • Classify rejected attributes with NativeAuthErrorV2.isInvalidAttributes() and retry AttributesRequiredStateV2.submitAttributes(...) on the retained state. Attribute-validation errors don't expose a new state.

Use MSALNativeAuthSignInParametersV2, MSALNativeAuthSignUpParametersV2, and MSALNativeAuthResetPasswordParametersV2 with their respective V2 entry points.

The Apple sampleiOS sample demonstrates V1 and V2 journeys. Follow the sample's setup instructions for its platform requirements.

  • Implement MSALNativeAuthFlowDelegate and each required per-state protocol. The callback handler needs to conform to the corresponding state protocol.
  • Handle onFlowCompleted(result:scenario:) and onFlowError(error:scenario:). Missing state-protocol implementation produces isNotImplemented.

JavaScript migration

The factory remains CustomAuthPublicClientApplication.create(customAuthConfig) and returns ICustomAuthPublicClientApplicationV2. The unified JavaScript sampleunified JavaScript samples include a React Next.js sample that demonstrates the matching V2 interfaces.

  • Replace V1 entry points with signInV2, signUpV2, and resetPasswordV2, passing the intended scopes and claims.
  • Check result.isFailed() before inspecting state. Then use result.isState("stateName") and retain result.state.
  1. Add the authorization-challenge operation and V2 native JSON requests.
  2. Separate OAuth form encoding from native JSON encoding. Use the latest continuation token with the correct property spelling for the endpoint.
  3. Replace constructed next-operation URLs with the links in the latest response. Resolve relative links against the custom-domainconfigured service authority, validate the hostname and tenant path, and reject an unexpected destination before sending secrets.
  4. Replace V1 challenge-type and capability branching with dispatch on the latest state and action. Select an available operation through application flow logic or user choice. Handle unknown optional fields and links without interrupting supported operations.

| Integration point | V1 | V2 | | Native redirect or browser-required error | The app stops native processing even when the response has no continuation token or links, then offers only a separately configured browser integration. | | Unusable required response | The app shows a clear failure or offers a supported browser sign-in without promising preservation of native progress. | | Throttling or ambiguous network failure | The app respects retry guidance and doesn't automatically replay credential verification or password updates. | | Custom-domainService authority routing | OAuth start, native operations, authorization continuation, and token redemption use the configured authority consistently. Browser-based apps require a verified custom domain and tenant GUID.GUID; non-browser native HTTP clients don't require a custom domain. A local proxy prefix remains transport configuration only. | | Unexpected link authority | No credential or continuation token is sent to a different hostname or tenant path. | | API access and sign-out | The intended resource accepts the correctly scoped access token; app-managed credentials and account UI are cleared on sign-out. Native logout doesn't terminate other application or browser sessions. |

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…