本机身份验证 API V2 参考

适用于: 绿色圆圈,带有白色复选标记符号,指示以下内容适用于外部租户。 外部租户(了解详细信息)

身份验证方法: 嵌入式本机身份验证。

本机身份验证 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和待定选择的 a continuationToken 。
  • 一个 _embedded.user 数组,其中包含有关每个提供的帐户和支持的链接的信息。 活动帐户具有特定于帐户的 _links.resume URL。
  • 非活动帐户的响应级别 _links.discover URL 或使用 另一个帐户。

身份验证方法资源

现有凭据方法选择使用 _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。 有关特定于事件的行为的 自定义身份验证扩展 ,请参阅。 此事件集不建立密码迁移挂钩、密码更新同步或任意上下文传播。