适用于:
外部租户(了解详细信息)
身份验证方法: 嵌入式本机身份验证。
本机身份验证 API 在Microsoft Entra 外部 ID外部租户中使用响应驱动的流。 启动授权,完成返回的身份验证交互,恢复授权,并交换令牌的授权代码。 此引用定义共享操作;特定于旅程的引用定义登录发现、注册属性和密码重置。
对于现有的 V1 集成,请使用 V1 API 参考。 有关包版本、迁移要求和 SDK 集成详细信息,请参阅 从 V1 迁移到 V2 。
Prerequisites
Important
本机身份验证 API V2 以预览版提供。 本机身份验证 API V1 仍然正式发布。 有关适用于预览功能的法律条款,请参阅Microsoft Azure预览版的补充使用条款。
- 为公共客户端和本机身份验证流配置的外部租户和应用程序。 请参阅 “配置应用程序”。
- 与应用程序关联的用户流。
- 对于基于浏览器的应用(如 SPA),为服务 API 调用配置的租户验证的自定义 URL 域。
- 如果请求对 API 的访问权限,则目标资源所需的委派权限和许可。
- 对于具有嵌入式本机身份验证和 BYO UX 网站的 SPA,是实现 浏览器代理要求的代理或边缘策略。
操作和授权
这些示例使用 https://{custom_domain}/{tenant}租户 custom_domain 验证的身份验证域,例如 login.contoso.com,其 tenant 目录(租户)ID(GUID)。
client_id 是应用程序(客户端)ID。 在这些示例中,所有服务 API 调用 URL 都使用此自定义域,包括授权质询和令牌交换。
本机身份验证 API V2 需要基于浏览器的应用(如 SPA)的租户验证自定义域,以帮助防止跨站点请求伪造(CSRF)。 非浏览器客户端(例如使用本机 HTTP 传输的 iOS 和 Android 应用)不需要自定义域。 嵌入式浏览器或 Web 视图不是本机 HTTP 传输。 BYO UX 仍基于浏览器,需要租户验证的自定义域。 请参阅 配置 API 机构。
除了初始授权请求和令牌交换,请使用当前响应播发的 URL。 方法 ID 不透明。 针对配置的颁发机构源解析相对链接,验证目标,并保留返回的路径和查询不变。
下面的授权开始、恢复和代码交换描述了嵌入式本机身份验证。 BYO UX 页面改用浏览器切换并返回有关共享本机交互操作的完成链接。 请勿在该 BYO UX 事务中启动或恢复 /authorize-challenge 。
| 操作 | Method | 路径或链接 |
|---|---|---|
| 启动授权 | POST |
/{tenant}/oauth2/v2.0/authorize-challenge |
| 恢复授权 | POST |
continue返回的链接。 |
| 开始登录 | POST |
sign_in返回的链接;示例使用 /{tenant}/api/v2.0/signin/start。 |
| 开始注册 | POST |
sign_up返回的链接;示例使用 /{tenant}/api/v2.0/signup/start。 |
| 提交注册属性 | POST |
submitAttributes返回的链接。 |
| 启动密码重置 | POST |
返回的重置密码链接;示例使用 /{tenant}/api/v2.0/resetpassword/start。 |
| 开始内联密码重置 | POST |
密码方法返回 recover 的链接。 |
| 注册身份验证方法 | POST |
所选方法返回 enroll 的链接。 |
| 激活身份验证方法 | POST |
activate返回的链接。 |
| 质询或重新发送 | POST |
challenge返回或resend链接。 |
| 验证凭据 | POST |
verify返回的链接。 |
| 更新密码 | PUT |
update返回的链接。 |
| 轮询密码更新 | POST |
poll返回的链接。 |
| Exchange授权代码 | POST |
/{tenant}/oauth2/v2.0/token |
本机示例使用 /api/v2.0;OAuth 操作使用 /oauth2/v2.0。 在这些颁发机构示例中使用租户 GUID。 遵循返回的链接,而无需重写其路径、版本或查询参数。
Headers
OAuth 和本机身份验证操作使用不同的正文编码。
| 页眉 | Use |
|---|---|
Content-Type: application/x-www-form-urlencoded |
授权质询和令牌请求所必需的。 |
Content-Type: application/json |
本机身份验证请求正文是必需的。 |
Accept: application/hal+json |
建议用于本机身份验证请求。 |
client-request-id: {guid} |
推荐。 为每个流生成一个新值,并将其保留用于诊断。 |
浏览器代理要求
这些要求适用于使用嵌入式本机身份验证和 BYO UX 网站的 SPA 的浏览器 API 调用。 使用本机 HTTP 传输的 Android 和 iOS 应用不需要 CORS 配置或 CORS 代理。
本机身份验证路由句柄OPTIONS,但不授予浏览器源访问权限。Access-Control-Allow-Origin 因此,跨域浏览器集成需要一个代理或边缘配置,
- 转发服务成功的预检响应并应用配置的浏览器源策略。
- 返回
Access-Control-Allow-Origin该确切允许的原点,而不是*。 - 允许操作的必需
POST或PUT方法和集成使用的请求标头。 - 保留请求正文、响应状态代码、内容类型和事务链接,而无需缓存身份验证响应。
- 跨授权、本机操作和令牌交换一致处理源和路由。
- 保留重试指南,包括
Retry-After在需要时将其公开给浏览器代码。
有关浏览器边界和本地代理配置的开发,请参阅本机身份验证 CORS 概念。
续传令牌
延续令牌表示其当前阶段的身份验证事务。 它绑定到租户、客户端、方案和操作。
| 消息格式 | 领域 |
|---|---|
| OAuth | continuation_token |
| 本机身份验证 API | continuationToken |
仅对同一响应标识的操作使用当前令牌。 不要分析、修改、记录或将其保存到活动事务之外。 当响应提供替换时,请停止使用以前的令牌。 不要将令牌移动到其他用户或旅程。 过期后重启授权。
记录的默认有效期为单个继续标记的 10 分钟。 根据服务响应处理过期;较新的令牌不能保证延长整个旅程。 令牌和一次性密码具有单独的生存期。 授权代码是生存期较短且单一使用的;不要将令牌响应 expires_in 解释为授权代码生存期。
响应模型
成功的本机交互操作返回 HAL JSON。 即使连续调用同一终结点,下一个操作也会有所不同。 字段特定于响应:例如,重定向只能 state包含 。
| 成员 | Purpose |
|---|---|
continuationToken |
包含下一个允许的请求的令牌。 |
state |
当前事务状态。 |
action |
响应所需的 interactionRequired 交互。 |
_links |
允许的操作的 URL。 |
_embedded |
相关资源,包括可用的方法。 |
流概念说明了状态和操作。 对于 interactionRequired,使用允许的操作处理返回的操作。 对于 continue,请通过返回的链接恢复授权。 单个操作 completed 的状态未确认已颁发令牌。
无法继续的本机事务可以返回:
{
"state": "redirect"
}
此响应不提供延续令牌、链接或浏览器交接 URL。 停止本机请求并提供单独配置的浏览器登录或清除失败。 浏览器登录将重启身份验证;它不会恢复本机进度。
帐户选择操作
注释
帐户选择在嵌入式本机身份验证中不相关,但 BYO UX 自承载页面尚不支持。
disambiguate 标识帐户选择下 state: interactionRequired。
链接关系
在转发机密之前,请使用最新响应中的链接并验证其权威。
| 关系 | Purpose |
|---|---|
self |
当前资源或操作。 |
discover |
提交登录标识符。 |
challenge |
启动所选方法的挑战。 |
verify |
验证密码或一次性密码。 |
resend |
请求另一次性密码。 |
submitAttributes |
提交请求的注册值。 |
recover |
在活动登录事务中启动密码恢复。 |
enroll |
开始注册播发的身份验证方法。 |
activate |
验证已注册方法的代码。 |
update |
提交替换密码。 |
poll |
检查异步更新。 |
continue |
恢复 OAuth 授权。 |
此操作与“自带 UX”(BYO UX)帐户选择相关。 嵌入式本机身份验证集成不使用它,目前不支持自承载 BYO UX 页上的帐户选择。
如果 BYO UX 集成遵循建议的解决方法,则发送 login_hint 或 prompt=login 发送授权请求时,引入帐户选择不会中断或中断现有的 UX。
操作有效负载是现有 BYO UX 浏览器交接的一部分, initialResponse 包括:
-
state: interactionRequired、action: disambiguate和待定选择的 acontinuationToken。 - 一个
_embedded.user数组,其中包含有关每个提供的帐户和支持的链接的信息。 活动帐户具有特定于帐户的_links.resumeURL。 - 非活动帐户的响应级别
_links.discoverURL 或使用 另一个帐户。
身份验证方法资源
现有凭据方法选择使用 _embedded.methods。 该服务还可以选择单个方法。 现有凭据具有不透明 id、 type 例如 password、 email或 sms允许操作的链接。 掩码 hint 标识目标而不完全披露目标; isPreferred 是可选的首选项元数据。 注册选项具有单独的表示形式,不需要现有的凭据 ID。
{
"_embedded": {
"methods": [
{
"id": "{id}",
"type": "email",
"hint": "u***@contoso.com",
"isPreferred": true,
"_links": {
"challenge": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{id}/challenge"
},
"verify": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{id}/verify"
}
}
}
]
}
}
此片段说明了方法元数据。 方法可用性是为每个事务确定的。 应用可以提供可用的方法,也可以通过应用程序流逻辑选择一种方法。 质询和验证对所选方法进行操作;方法注册具有单独的协定。
不需要可选演示文稿元数据,例如 pages 或 scenario。 这些示例介绍基本密码和电子邮件/短信交互,而不是每个特定于方法的要求。
启动授权
在初始请求上发送应用程序、范围和可选声明。 表单编码值;下面的换行符用于可读性。
POST https://{custom_domain}/{tenant}/oauth2/v2.0/authorize-challenge
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
scope=openid%20profile%20offline_access&
response_type=code
| Parameter | Use |
|---|---|
client_id |
必需的应用程序(客户端)ID。 |
scope |
限定应用程序请求的范围。 包括生成的令牌所需的 OpenID Connect(OIDC)和资源范围。 |
response_type |
code 在此示例中。 身份验证后,终结点将返回授权代码。 |
claims |
可选的 JSON 编码 OpenID Connect 声明请求。 |
当需要身份验证时,响应为 401 Unauthorized: Content-Type: application/json:
{
"error": "InsufficientAuthorization",
"error_description": "AADSTS500127: No authenticated credentials found in request.",
"error_codes": [
500127
],
"timestamp": "2026-08-28T17:30:00Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
"continuation_token": "******",
"reset_password": "/{tenant}/api/v2.0/resetpassword/start",
"sign_in": "/{tenant}/api/v2.0/signin/start",
"sign_up": "/{tenant}/api/v2.0/signup/start"
}
登录和注册 URL 是有条件的。 旅程链接是顶级 OAuth 响应属性,而不是 _links 条目。 选择播发旅程,并在 JSON 请求中发送其令牌 continuationToken 。 处理任何策略或帐户特定的拒绝。
恢复授权
当当前响应返回 state: continue时,将最新令牌 _links.continue.href发布到 。 请勿重新发送初始client_id请求或scopeclaims在此请求中。
POST https://{custom_domain}/{tenant}/oauth2/v2.0/authorize-challenge
Content-Type: application/x-www-form-urlencoded
continuation_token={continuation_token}
成功的响应为 200 OK JSON:
{
"code": "{authorization_code}"
}
授权代码是生存期较短且一次性的。 Exchange代码,而不是将其视为访问令牌。
Exchange授权代码
发布具有相同应用程序 ID 的代码:
POST https://{custom_domain}/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&
grant_type=authorization_code&
code={authorization_code}
这三个参数都是必需的。
grant_type 是 authorization_code. 此公共客户端请求不包含客户端密码。
成功的响应为 200 OK JSON:
{
"token_type": "Bearer",
"expires_in": 3600,
"access_token": "******",
"id_token": "******",
"refresh_token": "******"
}
令牌字段取决于最初建立的范围和声明。 仅当初始请求包含 offline_access时,才会返回刷新令牌。 示例过期值不是固定生存期保证。 如果应用程序不需要刷新令牌,请不要请求 offline_access 。
质询或重新发送
当客户请求其他密码时,请遵循所选方法 challenge 的链接或当前 resend 链接:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/{methodType}/{id}/challenge
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******"
}
电子邮件质询可以返回:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "verify",
"id": "{email_method_id}",
"type": "email",
"hint": "u***@contoso.com",
"codeLength": 8,
"_links": {
"verify": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/verify"
},
"resend": {
"href": "/{tenant}/api/v2.0/auth/methods/email/{email_method_id}/challenge"
}
}
}
SMS 使用相同的凭据质询形状,带有 type: sms屏蔽的电话提示及其返回的方法链接。 密码质询不发送密码并返回密码 verify 操作。 使用返回 codeLength的,而不是示例长度。 遵循服务控制的尝试并重新发送限制。
验证凭据
发布到当前 verify 链接。 对于密码方法:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/password/{id}/verify
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"password": "******"
}
对于电子邮件或短信方法:
POST https://{custom_domain}/{tenant}/api/v2.0/auth/methods/{methodType}/{id}/verify
Content-Type: application/json
Accept: application/hal+json
{
"continuationToken": "******",
"otp": "{one_time_passcode}"
}
验证可以返回另一个质询、属性集合、密码更新或延续。 处理返回的操作。 验证不是幂等的;在网络故障不明确后,请勿自动重试。
Authentication-method enrollment
注册或登录可能需要内联注册 action: enroll,然后 action: activate通过。 注册独立于收集配置文件属性或验证现有凭据。
Important
注册与使用已注册方法的身份验证分开。 仅使用为当前事务播发的注册方法;不要从凭据质询推断注册操作。
选择并注册方法
从 _embedded.methods 中选择受支持的方法并遵循其 _links.enroll URL。
| Method | 广告 | 所需的 JSON 字段 |
|---|---|---|
| 电话短信 |
type: phone,与 sms in channels. |
continuationToken, phoneNumber 包括国家/地区代码和 channel: sms。 |
| 电子邮件地址 |
type: email。 |
continuationToken 和 email. 不要发送 。channel |
电话注册使用 type: phone,而不是 sms 现有短信质询方法使用的类型。 电话注册 URL 示例为 /{tenant}/api/v2.0/auth/methods/phone;电子邮件 URL 为 /{tenant}/api/v2.0/auth/methods/email。
POST与 JSON 一起使用,并遵循播发的 URL,而不是构造一个。
对于电话短信注册,正文为:
{
"continuationToken": "******",
"phoneNumber": "+1 2025550123",
"channel": "sms"
}
对于电子邮件注册,正文为:
{
"continuationToken": "******",
"email": "user@contoso.com"
}
服务发送密码并返回 action: activate、新的延续令牌和 activate 链接。 显示返回的 hint 掩码和 codeLength 存在时间。 电子邮件和短信可以使用不同的代码长度。
电话激活响应可以是:
{
"continuationToken": "******",
"state": "interactionRequired",
"action": "activate",
"id": "{phone_method_id}",
"type": "phone",
"channel": "sms",
"hint": "***0123",
"codeLength": 6,
"_links": {
"activate": {
"href": "/{tenant}/api/v2.0/auth/methods/phone/{phone_method_id}/activate"
},
"resend": {
"href": "/{tenant}/api/v2.0/auth/methods/phone"
}
}
}
使用实际响应中的字段和链接;电子邮件使用自己的方法类型、代码长度和链接。
激活或重新发送
使用最新continuationToken代码和用户代码otp将 JSON POST 发送到当前activate链接。 电话示例使用 /{tenant}/api/v2.0/auth/methods/phone/{phone_method_id}/activate;电子邮件使用自己的播发链接。 不要将激活代码提交到凭据 verify 的链接。
{
"continuationToken": "******",
"otp": "{one_time_passcode}"
}
如果激活响应播resend发,则发送仅包含该链接的最新 continuationToken JSONPOST。 该链接可以指向注册。 请勿保留或重新发送联系人详细信息;令牌携带注册上下文。
{
"continuationToken": "******"
}
在每个响应后替换活动令牌、链接、提示和代码长度。 在激活后继续处理返回的操作;仅 state: continue 允许恢复授权。 注册本身可以满足 MFA,因此并不总是需要单独的凭据质询。
innerError.code: invalidOneTimeCode为此invalidGrant,请保留当前激活令牌和播发的链接。 让用户更正代码或请求重新发送。 在不明确连接失败后,不要自动重播注册或激活。
Errors
OAuth 错误使用字段,例如error,error_descriptiontrace_id和correlation_id。 本机身份验证失败使用嵌套信封。 例如,不正确的电子邮件验证码可以使用以下代码返回 HTTP 400 :
{
"error": {
"code": "invalidGrant",
"message": "AADSTS50181: Unable to validate the otp.",
"timestamp": "2026-08-28T17:30:00Z",
"traceId": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
"innerError": {
"code": "invalidOneTimeCode"
}
}
}
使用稳定的代码来处理而不是本地化的消息。 属性验证可以返回error.innerError.code: attributeValidationError包含detailscode、message以及attributeIds可选或recovery可选suggestions项的条目。 在分析之前检查 HTTP 状态和内容类型;不要在应用中呈现意外的 HTML 错误正文。
| 条件 | 状态或错误 | 处理 |
|---|---|---|
| 无效的 OAuth 参数 | 400 invalid_request |
更正请求;不要更改重试。 |
| 无效或过期的代码 | 400 invalid_grant |
重启授权。 |
| 应用程序无效 | 400 invalid_client |
正确应用配置。 |
| 无效或未授权的范围 | 400 invalid_scope |
检查请求的范围和同意。 |
| 需要身份验证 | 401 InsufficientAuthorization |
遵循已启用的旅程链接。 |
| 无效的继续标记/状态 | 400 invalidRequest |
重启适用的流。 |
| 密码更新令牌过期 |
400 expiredToken 带有 innerError.code: expiredContinuationToken |
重启授权。 |
| 缺少验证码 | 400 invalidRequest |
更正缺少的输入。 |
| 电子邮件或短信验证码不正确 |
400 invalidGrant 带有 innerError.code: invalidOneTimeCode |
让用户使用可用当前验证状态更正代码,或遵循播发的重新发送链接。 不要自动重新提交。 |
| 激活代码不正确 |
400 invalidGrant 带有 innerError.code: invalidOneTimeCode |
保留当前激活令牌和播发的链接。 让用户更正代码或使用播发的重新发送操作。 不要自动重新提交。 |
| 需要浏览器交互 |
invalid_grant 带有 web_redirect_required |
停止本机请求并使用配置的交互式恢复路径。 不要将延续标记转发到任意 URL。 |
| 本机事务无法继续 | 本机正文 {"state":"redirect"} |
停止本机请求。 单独的浏览器登录不会保留本机进度。 |
| 限制 | 429 |
荣誉 Retry-After 和服务器指南。 |
网络和服务故障可以使用其他响应格式。 将意外内容类型视为显式失败。 该表描述了特定的常见情况,而不是每个操作的详尽错误目录。
安全性和诊断
对每个上游请求使用 HTTPS。 将密码、密码、延续令牌、代码和颁发的令牌保留在 URL、日志、遥测、异常、屏幕截图和支持附件之外。 不要缓存身份验证响应或跨用户共享事务状态。
拒绝意外的当局和重定向,而不是转发机密。 在出现不明确失败后,不要自动重试凭据验证、帐户创建提交或密码更新。
仅显示服务提供的屏蔽提示。 使用泛型发现失败,因此消息和方法呈现不会不必要的披露帐户存在。
保留安全诊断:HTTP 状态、操作类别、 client-request-id服务跟踪/相关 ID 和时间戳。 OAuth 名称使用下划线;本机身份验证错误名称使用 camel 大小写。 在不保留完整请求或响应正文的情况下提取这些诊断字段。
自定义身份验证扩展
事件配置和协定特定于每个扩展和旅程。 当扩展参与流时,应用将继续从服务响应中选择允许的操作。
本机事件覆盖范围包括 OnOtpSend 电子邮件和 OnTokenIssuanceStart。
OnAttributeCollectionStart 并且 OnAttributeCollectionSubmit 不支持嵌入式本机身份验证或自带 UX。 有关特定于事件的行为的 自定义身份验证扩展 ,请参阅。 此事件集不建立密码迁移挂钩、密码更新同步或任意上下文传播。