Microsoft Entra External ID

Native Authentication for External Identities

A direct, CORS-friendly API surface for building fully custom sign-in, sign-up, MFA, and password reset flows without redirecting users away from your application.

Explore the API

Native Auth APIs MSAL Popup & Redirect MFA & Registration Token Inspection Operator Mode

Detailed Documentation

Native Auth comes first in this lab, then compare MSAL Popup and Browser Redirect implementation trade-offs.

Guided Journey

Recommended order: Native Auth → MSAL Popup → MSAL Redirect. Steps are softly gated, but you can skip and continue anytime.

What is Native Authentication?

Native Authentication lets your application call Entra External ID endpoints directly using standard OAuth 2.0 grants — no hosted login page required. Your UI stays in full control at every step.

🔑

Full UI Control

Design and brand every step of the authentication journey. No redirects, no hosted pages, no compromise on user experience.

📡

Direct API Access

Calls are made through a local CORS proxy in development. Each step returns a continuation token that drives the next request.

🔒

MFA & Registration

Handles MFA challenges (OTP via email/SMS), strong method registration, and self-service password reset — all within the same API contract.

🔄

Token Renewal

Use the issued refresh token to silently renew sessions via the same token endpoint, extending user sessions without re-authentication.

API Reference

All endpoints are relative to your tenant authority: https://{subdomain}.ciamlogin.com/{tenantId}

POST

/oauth2/v2.0/initiate

Start a sign-in flow and obtain the first continuation token

▼

Parameters

Param	Required	Description
`client_id`	✓	App registration client ID
`username`	✓	User's email / UPN
`challenge_type`	✓	Space-separated list: `password oob redirect`. Must include `redirect` as required fallback.

Response

Field	Description
`continuation_token`	Opaque token to pass to /challenge
`challenge_type`	`redirect` when app must fall back to hosted login

Common Errors

Error / Suberror	Cause
`user_not_found`	No account with that username
`nativeauthapi_disabled`	Native Auth not enabled for tenant
`invalid_client`	Incorrect client_id or app not registered

{
  "client_id": "...",
  "username": "user@contoso.com",
  "challenge_type": "password oob redirect"
}

POST

/oauth2/v2.0/challenge

Select the authentication method for this user session

▼

Parameters

Param	Required	Description
`client_id`	✓	App registration client ID
`continuation_token`	✓	Token from /initiate or /token
`challenge_type`	✓	Supported types: `password oob redirect`
`id`		Method ID from /introspect (for MFA challenge selection)

Response

Field	Description
`challenge_type`	`password`, `oob`, or `redirect`
`continuation_token`	Updated token for next step
`challenge_channel`	OOB delivery channel (`email`)
`challenge_target_label`	Masked delivery address (e.g. `a***@c.com`)
`code_length`	Expected OTP length

{
  "challenge_type": "oob",
  "challenge_channel": "email",
  "challenge_target_label": "u***@contoso.com",
  "code_length": 8,
  "continuation_token": "..."
}

POST

/oauth2/v2.0/token

Verify credential and issue access, ID, and refresh tokens

▼

Parameters

Param	Required	Description
`client_id`	✓	App registration client ID
`grant_type`	✓	See grant types table below
`continuation_token`	✓	Current continuation token (most flows)
`scope`	✓	`openid offline_access profile`
`password`		User's password (grant_type=password)
`oob`		OTP code (grant_type=oob or mfa_oob)
`refresh_token`		Existing refresh token (grant_type=refresh_token)

Grant Types

grant_type	When to use
`password`	First-factor password authentication
`oob`	First-factor email OTP authentication
`mfa_oob`	MFA second factor (email OTP)
`continuation_token`	Complete registration or pending flow
`attributes`	Supply sign-up custom attributes
`refresh_token`	Silent session renewal with stored token

Token Response

Field	Description
`access_token`	JWT; use for API authorization
`id_token`	JWT; user identity claims (`openid` scope required)
`refresh_token`	Opaque; for session renewal (`offline_access` scope required)
`expires_in`	Access token lifetime in seconds
`scope`	Granted scopes

Conditional Responses

Suberror	Meaning	Next step
`mfa_required`	MFA step required	Call /introspect then /challenge with method ID
`registration_required`	Must enroll MFA method	Call /register/v1.0/introspect
`invalid_oob_value`	Wrong OTP entered	Show error, allow retry
`password_too_weak`	Password policy violation	Show policy requirements

POST

/oauth2/v2.0/introspect

Discover registered MFA methods for the user

▼

Parameters

Param	Required	Description
`client_id`	✓	App registration client ID
`continuation_token`	✓	Token received after mfa_required suberror

Response

Field	Description
`continuation_token`	Fresh token to use in /challenge
`methods[]`	Array of method objects
`methods[].id`	Method ID to pass to /challenge as `id` param
`methods[].challenge_type`	e.g. `oob`
`methods[].challenge_channel`	e.g. `email`
`methods[].login_hint`	Masked target for display

POST ×3

/register/v1.0/{introspect · challenge · continue}

Enroll a strong authentication method during sign-up or first sign-in

▼

/register/v1.0/introspect

Lists enrollable MFA methods. The continuation token comes from a registration_required response from /oauth2/v2.0/token.

Param	Required
`client_id`	✓
`continuation_token`	✓

/register/v1.0/challenge

Send enrollment challenge OTP to the user's target.

Param	Required
`client_id`	✓
`continuation_token`	✓
`challenge_type`	✓
`challenge_target`	✓

/register/v1.0/continue

Submit the OTP to complete enrollment and return to the token flow.

Param	Required
`client_id`	✓
`continuation_token`	✓
`grant_type`	✓ (`oob`)
`oob`

Note: After successful /register/v1.0/continue, call /oauth2/v2.0/token again with grant_type=continuation_token to complete the full authentication and receive tokens.

Authentication Flows

Each flow is a sequence of API calls connected by continuation tokens. Every step must receive and forward the latest token.

Sign-In

Email + Password

POST /initiate — start sign-in, obtain continuation token
POST /challenge — Entra selects authentication method
POST /token with grant_type=password — verify credential
✓ Receive access_token, id_token, refresh_token

If /token returns mfa_required → continue with MFA flow below.

MFA Extension

Multi-Factor Authentication

Triggered when /token returns suberror=mfa_required
POST /introspect — get list of enrolled MFA methods
User selects method from the returned list
POST /challenge with selected method id — delivery OTP
User enters received OTP code
POST /token with grant_type=mfa_oob + oob value
✓ Receive final token set

Registration

Strong Method Enrollment

Triggered when /token returns suberror=registration_required
POST /register/v1.0/introspect — list enrollable methods
User selects method to enroll
POST /register/v1.0/challenge — send enrollment OTP
User enters received OTP code
POST /register/v1.0/continue with grant_type=oob + oob value
POST /token with grant_type=continuation_token — finalize
✓ Receive token set

Renewal

Session Renewal (Refresh Token)

Store refresh_token from initial sign-in token response
POST /token with grant_type=refresh_token + stored token
✓ Receive new access_token, id_token, and optionally a rotated refresh_token

Refresh tokens expire or are revoked. Always handle failure and prompt re-authentication if renewal fails.

SSPR

Self-Service Password Reset

POST /resetpassword/v1.0/start — initiate with username
POST /resetpassword/v1.0/challenge — deliver OTP
User enters OTP code
POST /resetpassword/v1.0/continue — verify OTP
POST /resetpassword/v1.0/submit — submit new password
GET /resetpassword/v1.0/poll_completion — poll until success
✓ Password updated; prompt user to sign in

Redirect Fallback

Any endpoint may return challenge_type=redirect
This is a control response, not a transport error
Your app must fall back to a hosted sign-in page (MSAL popup or redirect)
Always advertise redirect in your challenge_type list to satisfy API requirements

This demo handles redirect fallback by switching to MSAL popup or redirect flows.

Key Concepts

🔗 Continuation Token

An opaque, short-lived token that connects sequential API calls within the same flow. You must propagate the most recent continuation token to each subsequent request. Tokens are endpoint-sequence specific — using one out of order will fail.

🎯 Challenge Types

Values that declare which authentication method is requested or supported. Always include redirect in your advertised list as a required fallback. Common values: password, oob, redirect.

🔏 Grant Types

The credential mechanism used at the token endpoint. The correct grant type depends on flow stage: password for first-factor, oob/mfa_oob for OTP steps, refresh_token for renewal, continuation_token after registration.

📋 Error Contract

All error responses include error, error_description, suberror (for branching), trace_id, and correlation_id. Always capture trace_id for support escalation. Treat expired_token as a signal to restart the flow.

🚦 Scopes

Request openid offline_access as a minimum. Add profile for name/email claims in the ID token. Add Microsoft Graph scopes (e.g. User.Read) to authorize Graph API calls with the resulting access token.

🛡️ CORS Proxy

Native Auth endpoints do not support browser CORS. A local forwarding proxy (cors.js, running on port 3001) transparently proxies all /api/* requests from the browser to the Entra endpoints during development.

Best Practices & Error Handling

✓ Do

Always include redirect in challenge_type to comply with API requirements
Capture trace_id and correlation_id from every error response for support diagnostics
Handle expired_token by restarting the current flow from /initiate
Implement bounded retry (max 3 attempts) for invalid_oob_value
Treat challenge_type=redirect as a legitimate control path, not a failure
Store refresh tokens in sessionStorage, not localStorage
Request offline_access scope at token step to receive a refresh token

✗ Don't

Omit redirect from challenge_type — API may reject unsupported challenges
Reuse a continuation token after it has been consumed by a successful call
Assume a continuation token is valid after navigating away — restart if unsure
Retry interaction_required or consent_required errors silently — they require user action
Store credentials or tokens in plaintext files or source control
Call Native Auth endpoints directly from the browser without a CORS proxy in development

Common Error Codes

error	suberror	Meaning	Recovery
`invalid_grant`	`mfa_required`	MFA second factor required	Call /introspect, then /challenge with method ID
`invalid_grant`	`registration_required`	User must enroll MFA method	Start /register/v1.0 flow
`invalid_grant`	`invalid_oob_value`	Wrong OTP entered	Show error, allow bounded retry
`invalid_grant`	`password_too_weak`	Password fails policy	Show policy requirements
`invalid_grant`	`expired_token`	Continuation token expired	Restart flow from /initiate
`invalid_client`	`nativeauthapi_disabled`	Native Auth not enabled	Enable in Entra portal tenant settings
`user_not_found`	—	No account with that username	Check username, offer sign-up
`unauthorized_client`	—	App not configured for this flow	Check app registration in Entra portal

Production Hardening Checklist

This starter is optimized for learning. Validate these items before production rollout.

Keep raw token values hidden in production and remove demo-mode token reveal controls.
Prefer secure, server-backed session/token handling over browser persistence for sensitive workloads.
Review redirect URIs, token scopes, and consent requirements across all environments.
Log and monitor only safe diagnostics: never log token values or full auth payloads.
Validate accessibility, error recovery, and browser compatibility for your supported audience.

MSAL Browser Redirect Flow

Redirect is broadly compatible and reliable when popup is blocked, but causes full-page navigation away from app state.

Redirect Mechanics

How it works

App calls loginRedirect().
Browser navigates to Microsoft identity endpoint.
After sign-in, browser returns to configured redirect URI.
App processes response in handleRedirectPromise().

Edge Cases

What to handle

Lost transient UI state if not persisted before redirect.
Return-route and deep-link continuity for complex SPAs.
Multi-tab flows and stale interaction state.

Popup vs Redirect: Deep Comparison

Use this matrix as an architecture decision aid for your product and platform constraints.

Dimension	MSAL Popup	MSAL Redirect
UX continuity	Strong continuity in same page context.	Full page navigation breaks continuity temporarily.
Browser constraints	Can fail with popup blockers or strict policies.	More reliable across restrictive browser settings.
Security & token handling	Same token semantics; fewer route re-entry concerns.	Requires careful redirect URI and state handling.
Error recoverability	Inline recovery feels immediate.	Recovery often handled after navigation roundtrip.
Implementation complexity	Simpler UX integration, more popup fallbacks needed.	Predictable flow, but more app-state restoration logic.
Accessibility	Popup context switch can confuse some assistive tech users.	Single-window navigation can be easier to follow.

Ready to explore the flows end-to-end?

Download Postman Collection

CodexJay External ID

Entra-style sign-in experience

CodexJay Identity Platform

Global-ready External ID authentication experience

Clean, modern sign-in flows for enterprise onboarding, partner access, and customer identity journeys.

Native, popup, and redirect authentication patterns
MFA challenge and method registration support
Live token and auth-method visibility for demos

Sign in

Use a supported authentication option

Starter app guardrail: This demo may expose raw token tools for learning. View production hardening checklist.

Native Auth

Best for API-driven, fully customized journeys.

Direct flow control

MSAL Popup

Great UX continuity, but can be blocked by browser policy.

Context preserved

MSAL Redirect

Most compatible fallback for restrictive browser environments.

Strong compatibility

Welcome

You are an HCP You are not an HCP

Entra User Profile

Graph profile fields ($select)

Comma-separated Microsoft Graph /me fields. Click Apply to reload profile data.

Claim Provenance

Token Details

Production safety: Keep token inspection tooling scoped to demo/test environments. Review hardening checklist.

Demo mode is enabled. Raw token values are visible and should only be used in controlled environments.

Registered Authentication Methods

Loading authentication methods...

Operator Beta Insights

This panel uses Microsoft Graph beta endpoints and requires operator mode plus elevated Graph permissions.

Choose your learning path

Native Authentication for External Identities

Detailed Documentation

Guided Journey

What is Native Authentication?

Full UI Control

Direct API Access

MFA & Registration

Token Renewal

API Reference

Parameters

Response

Common Errors

Parameters

Response

Parameters

Grant Types

Token Response

Conditional Responses

Parameters

Response

/register/v1.0/introspect

/register/v1.0/challenge

/register/v1.0/continue

Authentication Flows

Email + Password

Multi-Factor Authentication

Strong Method Enrollment

Session Renewal (Refresh Token)

Self-Service Password Reset

Redirect Fallback

Key Concepts

🔗 Continuation Token

🎯 Challenge Types

🔏 Grant Types

📋 Error Contract

🚦 Scopes

🛡️ CORS Proxy

Best Practices & Error Handling

Common Error Codes

Production Hardening Checklist

MSAL Popup Flow

How it works

What can fail

MSAL Browser Redirect Flow

How it works

What to handle

Popup vs Redirect: Deep Comparison

Ready to explore the flows end-to-end?

Global-ready External ID authentication experience

Sign in

Native Auth

MSAL Popup

MSAL Redirect

Welcome

Entra User Profile

Claim Provenance

Token Details

Registered Authentication Methods

Operator Beta Insights

User detail

Authentication requirements

Sign-in preferences

Registration posture

Tenant method adoption