本机身份验证 API V1 参考

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

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

此参考文档记录了现有集成的 V1 协定。 对于特定于库的接口,请使用 SDK 引用。

使用 嵌入式本机身份验证,应用程序会显示身份验证接口。 Microsoft Entra 外部 ID验证身份验证请求时,可以控制其布局和交互。

此 V1 API 参考介绍了用于维护集成的原始 HTTP 请求。 有关现有库集成,请参阅 SDK 库引用。

旅程响应包含下一操作所需的信息。 根据请求和终结点协定,令牌响应可以包括用于用户标识的 ID 令牌 和受保护 API 的访问令牌 。

本机身份验证 API 支持注册和登录两个身份验证流:

  • 电子邮件和密码,它支持使用电子邮件和密码进行注册和登录,以及自助式密码重置 (SSPR)。

  • 电子邮件一次性验证码,支持使用电子邮件一次性密码进行注册和登录。

浏览器 CORS 要求

Note

本机身份验证 API V1 终结点不支持通过 跨源资源共享(CORS)直接跨源浏览器访问。 现有浏览器集成需要代理。 使用本机 HTTP 传输的 Android 和 iOS 应用不需要 CORS 或 CORS 代理。

为客户端使用的 V1 终结点路径配置代理。

SDK 引用

使用与已安装的包匹配的库引用。 链接的文档还可以描述较新的 SDK 接口;本文定义 V1 HTTP 协定。

Prerequisites

  1. Microsoft Entra 外部租户。 如果还没有外部租户,可以创建一个。

  2. 如果尚未完成此操作,请在 Microsoft Entra 管理中心注册应用程序。 请确保:

  3. 如果尚未执行此作,在Microsoft Entra管理中心创建用户流。 创建用户流时,请记下你根据需要配置的用户属性,因为这些属性是Microsoft Entra你的应用需要提交的属性。

  4. 将应用注册与用户流相关联。

  5. 登录流程时,注册 一个客户用户,用来测试流程。 或者,也可以在运行注册流之后获取该测试用户。

  6. 如果是 SSPR 流,则为外部租户中的客户用户启用自助式密码重置。 SSPR 适用于具有密码验证方法的电子邮件的客户用户。

  7. 如果你想让使用电子邮件地址和密码登录的用户也能用用户名和密码登录,请使用“ 用别名或用户名登录 ”文章中的步骤:

    1. 在登录中启用用户名。
    2. 在管理中心创建用户名的用户,或通过添加用户名更新现有用户。 或者,还可以 使用 Microsoft 图形 API 在应用中自动创建和更新用户。
  8. 若要为客户强制实施多重身份验证( MFA),请使用向应用添加多重身份验证(MFA) 中的步骤将 MFA 添加到登录流。 本机身份验证支持电子邮件一次性密码和短信作为 MFA 的第二个因素。

继续标记

每当调用登录、注册或 SSPR 终结点时,响应将包含 延续令牌。 此令牌唯一标识当前流,并允许Microsoft Entra ID在其终结点上保持状态。 在该流中的每个后续请求中包含令牌。 它仅在有限的时间内有效,并且只能用于同一流中的后续请求。

V1 挑战类型和功能

V1 客户端通过 challenge_type 其他 UI 和流支持 capabilities来播发身份验证方法。

挑战类型 Description
password 此质询类型表示应用支持从用户收集密码凭据。
oob 此质询类型表示应用程序支持通过辅助通道发送给用户的一次性密码或通行码(OTP)代码。 目前,API 仅支持电子邮件和短信 OTP。
重定向 此质询类型表示应用程序支持回退到浏览器委托的身份验证,也称为 Web 回退。 所有符合本机身份验证的应用都必须支持此功能。 此要求意味着,在应用对本机身份验证 API 进行的每个调用中,它都必须包含此质询类型。 如果客户端应用无法包含此质询类型,请求将失败。
身份验证方法 注册 Sign-in 自助密码重置
带密码的电子邮件 oob password redirect oob password redirect oob redirect
电子邮件一次性密码 oob redirect oob redirect 不適用。

直接 API 客户端包括在 redirect 声明质询类型时。 V1 Android、iOS 和 JavaScript SDK 会自动包含它。

Capability Meaning
mfa_required 客户端可以处理内联 MFA,包括 /introspect、 /challenge序列和 /token 相应的 UI。 这包括租户策略要求时身份验证上下文驱动的 MFA。
registration_required 客户端可以调用强身份验证方法注册 API 并显示注册 UI。

不支持的挑战类型或功能使请求无效。 如果客户端省略所需的质询类型,则服务需要 Web 回退。 如果客户端省略 MFA 或注册功能,则仅当服务不需要该功能时,流才能继续;否则,需要 Web 回退。

V1 Web 回退切换到浏览器委托的身份验证。 例如,具有密码的电子邮件注册流需要和 oobpassword。 播发该流仅 oob 使用浏览器回退的应用。 使用 SDK 参考 进行平台错误检查和交互式库入口点。 浏览器回退会启动单独的身份验证尝试,而不是恢复本机进度。

启用公共客户端和原生身份验证流

对于你有权管理的现有 V1 应用程序注册:

对注册使用应用程序所有权或委派 的应用程序管理权限 。 身份验证设置不需要仅为此任务分配租户范围的管理员;同意和策略更改具有单独的权限要求。

  1. 在Microsoft Entra 管理中心中打开应用程序注册。
  2. 在“管理”下,选择“身份验证”。
  3. 在 “高级设置”下,设置 “启用以下移动和桌面流 ”,并将 “启用本机身份验证 ”设置为 “是”。
  4. 选择“保存”。

V1 用户名登录

你可以允许使用电子邮件地址和密码登录的用户也使用用户名和密码登录。 用户名也称为备用登录标识符,可以是客户 ID、帐户号或你选择用作用户名的另一个标识符。

可以通过 Microsoft Entra 管理中心手动将用户名分配给用户帐户,或者通过 Microsoft 图形 API 在应用中自动分配用户名。

使用 《使用别名或用户名登录》 文章中的步骤,让用户能够在你的应用程序中使用用户名登录。

  1. 在登录中启用用户名。
  2. 在管理中心创建用户名的用户 ,或通过 添加用户名将现有用户更新为。 或者,还可以 使用 Microsoft 图形 API 在应用中自动创建和更新用户。

注册时的API参考

要完成任一身份验证方法的用户注册流,应用需与四个终结点(/signup/v1.0/start、/signup/v1.0/challenge、/signup/v1.0/continue和/token)交互。

用于注册的API端点

Endpoint Description
/signup/v1.0/start 此终结点启动注册流。 传递有效的应用程序 ID、新用户名和质询类型,然后返回新的延续令牌。 如果应用程序选择的身份验证方法不受Microsoft Entra支持,终结点可以返回一个响应,以指示应用程序使用 Web 身份验证流。
/signup/v1.0/challenge 应用使用 Microsoft Entra 支持的 challenge 类型列表调用此终结点。 Microsoft Entra然后选择一种受支持的身份验证方法,供用户进行身份验证。
/signup/v1.0/continue 此终结点有助于继续流以创建用户帐户或中断流,因为缺少密码策略要求或错误的属性格式等要求。 此终结点生成延续令牌,然后将其返回到应用。 如果应用程序不是Microsoft Entra选择的身份验证方法,终结点可以返回一个响应,以指示应用程序使用基于 Web 的身份验证流。
oauth/v2.0/token 应用程序调用此终结点,以最终请求安全令牌。 应用需要使用它从上次成功调用终结点时获取的 /signup/v1.0/continue 延续令牌。

注册质询类型

API 允许客户端应用在调用Microsoft Entra时播发它支持的身份验证方法。 应用会使用应用请求中的challenge_type参数来进行播发。 此参数包含表示不同身份验证方法的预定义值。

请在本机身份验证质询类型中详细了解质询类型。 本文介绍应用于身份验证方法的质询类型值。

注册流协议详细信息

序列图演示了注册过程的流。

注册流的本机身份验证示意图。

此关系图指示应用收集用户名(电子邮件)、密码(用于具有密码身份验证流的电子邮件)以及不同时间(可能位于单独的屏幕上)的用户的属性。 但是,你可以设计应用以收集用户名(电子邮件)、密码以及同一屏幕中的所有必需属性值和可选属性值,然后将所有这些值提交到 /signup/v1.0/start 终结点。 如果应用将所有必需信息提交到 /signup/v1.0/start 终结点,则应用无需在可选步骤中发出调用并处理响应。

在步骤 21 中,用户已注册。 但是,如果应用需要在注册后自动登录用户,应用会调用 oauth/v2.0/token 终结点来请求安全令牌。

步骤 1:请求开始注册流

注册流开始,应用向 /signup/v1.0/start 终结点发送 POST 请求以开始注册流。

下面是请求的示例(我们在多行中演示示例请求,以便可读性):

示例 1:

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&username=contoso-consumer@contoso.com

示例 2(在请求中包含用户属性和密码):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&password={secure_password}
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{user_postal_code}"}
&username=contoso-consumer@contoso.com
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
username 是的 客户用户注册时要使用的电子邮件,例如 contoso-consumer@contoso.com。
challenge_type 是的 以空格分隔的应用支持的授权质询类型字符串列表,例如 oob password redirect。 列表中必须始终包含 redirect 质询类型。 对于具有密码身份验证方法的电子邮件,该值应为oob redirect或oob password redirect。
password No 应用从客户用户处收集到的密码值。 可以通过 /signup/v1.0/start 终结点中的 /signup/v1.0/continue 或更高版本提交用户的密码。 将 {secure_password} 替换为应用从客户用户处收集到的密码值。 你有责任通过提供应用 UI 中的密码确认字段来确认用户想要使用的密码。 还必须确保用户知道根据组织策略构成强密码的内容。 详细了解Microsoft Entra的密码策略。
此参数仅适用于使用密码身份验证方法的电子邮件。
attributes No 应用从客户用户处收集到的用户属性值。 该值是字符串,但采用 JSON 对象格式,其键值是用户属性的可编程名称。 这些属性可以内置或自定义,可以是必需或可选。 对象的键名称取决于管理员在Microsoft Entra管理中心配置的属性。 可以通过 /signup/v1.0/start 终结点或稍后在 /signup/v1.0/continue 终结点中提交部分或全部用户属性。 如果通过 /signup/v1.0/start 终结点提交全部必需的属性,则不需要在 /signup/v1.0/continue 终结点中提交任何属性。 但是,如果通过 /signup/v1.0/start 终结点提交部分必需的属性,则可以稍后在 /signup/v1.0/continue 终结点中提交剩余的属性。 将{given_name}、{user_age}、{postal_code}分别替换为应用从客户用户处收集到的姓名、年龄和邮政编码值。 Microsoft Entra忽略提交的任何属性,这些属性不存在。
capabilities No 描述客户端应用功能的空间分隔标志。 虽然 challenge_type 定义了哪些方法可能受到质询, capabilities 但告诉本机身份验证 API 客户端应用可以处理哪些额外的流,以及它可以向用户显示的 UI。 例如, mfa_required 表示另一个 /challenge 和 /token 循环; registration_required 表示客户端应用调用注册 API 并显示注册 UI。 如果客户端应用未播发所需的功能,API 将返回重定向。 支持的值是 mfa_required 和 registration_required。 详细了解功能。

成功响应

下面是成功响应的示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "AQABAAEAAA…"
}
Property Description
continuation_token Microsoft Entra返回的延续标记。

重定向响应

如果客户端应用不支持Microsoft Entra要求的身份验证方法或功能,则需要回退到基于 Web 的身份验证流。 在此方案中,Microsoft Entra通过在响应中返回 redirect 质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Property Description
challenge_type Microsoft Entra返回具有质询类型的响应。 此质询类型的值为 redirect,该值可让应用使用基于 Web 的身份验证流。

虽然此响应视为成功响应,但应用需要切换到基于 Web 的身份验证流。 这种情况下,建议使用 Microsoft 构建和支持的身份验证库。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "user_already_exists",
    "error_description": "AADSTS1003037: It looks like you may already have an account.... .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        1003037
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。
invalid_attributes 未通过验证的属性列表(一组对象)。 如果应用提交用户属性,并且 suberror 属性值 attribute_validation_failed,则此响应是可能的。
suberror 错误代码字符串,可用于对错误类型进行进一步分类。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,当 challenge_type 参数值包含不支持的身份验证方法,或请求未包含 client_id 参数,导致客户端 ID 值为空或无效。 使用 error_description 参数了解错误的具体原因。
invalid_client 应用包含在请求中的客户端 ID 是供缺少本机身份验证配置的应用使用的,例如,不是公共客户端或未启用本机身份验证。 使用该 suberror 属性可了解错误的确切原因。
unauthorized_client 请求中使用的客户端 ID 的格式有效,但外部租户中不存在或不正确。
unsupported_challenge_type challenge_type 参数值不包含 redirect 质询类型。
user_already_exists 用户已存在。
invalid_grant 应用提交的密码不符合所有复杂性要求,例如密码太短。 使用该 suberror 属性可了解错误的确切原因。
此参数仅适用于使用密码身份验证方法的电子邮件。

如果错误参数的值为 invalid_grant,则Microsoft Entra在其响应中包含 suberror 属性。 下面是suberror错误的属性的可能值:

Suberror 值 Description
password_too_weak 密码太弱,因为它不符合复杂性要求。 详细了解Microsoft Entra的密码策略。 如果应用提交用户密码,则此响应可能。
password_too_short 新密码少于 8 个字符。 详细了解Microsoft Entra的密码策略。 如果应用提交用户密码,则此响应可能。
password_too_long 新密码长度超过 256 个字符。 详细了解Microsoft Entra的密码策略。 如果应用提交用户密码,则此响应可能。
password_recently_used 新密码不得与最近使用的密码相同。 详细了解Microsoft Entra的密码策略。 如果应用提交用户密码,则此响应可能。
password_banned 新密码包含禁止的单词、短语或模式。 详细了解Microsoft Entra的密码策略。 如果应用提交用户密码,则此响应可能。
password_is_invalid 密码无效,例如,因为它使用不允许的字符。 详细了解Microsoft Entra的密码策略。 如果应用提交用户密码,则此响应可能。

如果错误参数的值为 invalid_client,则Microsoft Entra在其响应中包含 suberror 属性。 下面是suberror错误的属性的可能值:

Suberror 值 Description
nativeauthapi_disabled 未启用本机身份验证的应用的客户端 ID。

Note

如果通过 /signup/v1.0/start 终结点提交全部必需的属性,但并非全部都是为可选属性,则稍后将无法通过 /signup/v1.0/continue 终结点提交任何其他的可选属性。 Microsoft Entra不会显式请求可选属性,因为它们不需要注册流才能完成。 请参阅将用户属性提交到终结点部分中的表,以了解可以提交到/signup/v1.0/start终结点和/signup/v1.0/continue终结点的用户属性。

步骤 2:选择身份验证方法

应用请求Microsoft Entra为要进行身份验证的用户选择受支持的质询类型之一。 为此,应用会调用/signup/v1.0/challenge终结点。 应用需要包含它从请求中的/signup/v1.0/start终结点获取的延续令牌。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
challenge_type No 以空格分隔的应用支持的授权质询类型字符串列表,例如 oob password redirect。 列表中必须始终包含 redirect 质询类型。 对于电子邮件一次性密码,此值应为oob redirect,对于具有密码身份验证方法的电子邮件,此值应为oob password redirect。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。

成功响应

Microsoft Entra向用户的电子邮件发送一次性密码,然后使用值为 ob0 的质询类型进行响应,以及有关一次性密码的其他信息:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "interval": 300,
    "continuation_token": "AQABAAEAAAYn...",
    "challenge_type": "oob",
    "binding_method": "prompt",
    "challenge_channel": "email",
    "challenge_target_label": "c***r@co**o**o.com",
    "code_length": 8
}
Property Description
interval 在尝试重新发送 OTP 之前,应用需要等待的时间长度(以秒为单位)。
continuation_token Microsoft Entra返回的延续标记。
challenge_type 为用户进行身份验证所选择的质询类型。
binding_method 唯一的有效值为“prompt”。 将来可以使用此参数为用户提供更多输入一次性密码的方式。 如果 challenge_type 是 oob,则颁发
challenge_channel 发送一次性密码的通道的类型。 目前,仅支持电子邮件通道。
challenge_target_label 一封模糊的电子邮件,其中发送了一次性密码。
code_length Microsoft Entra生成的一次性密码的长度。

重定向响应

如果客户端应用不支持Microsoft Entra要求的身份验证方法或功能,则需要回退到基于 Web 的身份验证流。 在此方案中,Microsoft Entra通过在响应中返回 redirect 质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Property Description
challenge_type Microsoft Entra返回具有质询类型的响应。 此质询类型的值为 redirect,该值可让应用使用基于 Web 的身份验证流。

虽然此响应视为成功响应,但应用需要切换到基于 Web 的身份验证流。 这种情况下,建议使用 Microsoft 构建和支持的身份验证库。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如客户端 ID 为空或无效。
expired_token 延续令牌已过期。
unsupported_challenge_type challenge_type 参数值不包含 redirect 质询类型。
invalid_grant 延续令牌无效。

步骤 3:提交一次性密码

应用提交发送到用户电子邮件的一次性密码。 由于我们要提交一次性密码代码,因此需要 oob 参数,并且 grant_type 参数必须具有值 oob。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
grant_type 是的 可以使用对 /signup/v1.0/continue 终结点的请求提交一次性密码、密码或使用用户属性。 这种情况下,grant_type 值用于区分这三种用例。 grant_type 可能的值有oob、密码、属性。 在此调用中,由于发送的是一次性密码,因此该值应为 oob。
oob 是的 客户用户在其电子邮件中收到的一次性密码。 将{otp_code}替换为客户用户在其电子邮件中收到的一次性密码值。 要重新发送一次性密码,应用需要再次向 /signup/v1.0/challenge 终结点发出请求。

应用成功提交一次性密码代码后,注册流取决于如下表所示的方案:

Scenario 如何继续
应用通过 /signup/v1.0/start 终结点成功提交用户密码(用于密码身份验证方法的电子邮件),Microsoft Entra管理中心中未配置任何属性,或者所有必需的用户属性都通过 /signup/v1.0/start 终结点提交。 Microsoft Entra颁发延续令牌。 应用可以使用延续令牌请求安全令牌,如 安全令牌请求中所示。
应用通过 /signup/v1.0/start(而不是所有必需的用户属性)成功提交用户密码(用于密码身份验证方法的电子邮件),Microsoft Entra指示应用需要提交的属性,如 user 属性所需的属性所示。 应用需要通过/signup/v1.0/continue终结点提交所需的用户属性。 响应类似于用户属性中所需的响应。 提交用户属性,如提交用户属性中所述。
应用不会通过/signup/v1.0/start终结点提交用户密码(对于具有密码身份验证方法的电子邮件)。 Microsoft Entra的响应指示凭据是必需的。 请参阅响应。
此响应可用于使用密码身份验证方法的电子邮件。

Response

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "credential_required",
    "error_description": "AADSTS55103: Credential required. Trace ID: d6966055-...-80500 Correlation ID: 3944-...-60d6 Timestamp: yy-mm-dd 02:37:33Z",
    "error_codes": [
        55103
    ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABEQEAAAA..."
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。
continuation_token Microsoft Entra返回的延续标记。
suberror 错误代码字符串,可用于对错误类型进行进一步分类。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
credential_required 帐户创建需要身份验证,因此必须调用 /signup/v1.0/challenge 终结点来确定用户需要提供的凭据。
invalid_request 请求参数验证失败,例如,延续令牌验证失败或请求未包含 client_id 参数,导致客户端 ID 为空或无效,或者外部租户管理员并未给所有租户用户都启用电子邮件 OTP 租户。
invalid_grant 请求中包含的授权类型无效或不受支持,或者 OTP 值不正确。
expired_token 请求中包含的延续令牌已过期。

如果错误参数的值为 invalid_grant,则Microsoft Entra在其响应中包含 suberror 属性。 下面是suberror错误的属性的可能值:

Suberror 值 Description
invalid_oob_value 一次性密码的值无效。

若要从用户收集密码凭据,应用需要调用 /signup/v1.0/challenge 终结点以确定用户需要提供的凭据。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob password redirect
&continuation_token=AQABAAEAAA…
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
challenge_type No 以空格分隔的应用支持的授权质询类型字符串列表,例如 oob password redirect。 列表中必须始终包含 redirect 质询类型。 如果是电子邮件和密码注册流,则值中应包含 password redirect。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。

成功响应

如果密码是在 Microsoft Entra 管理中心为用户配置的身份验证方法,则会向应用返回包含延续令牌的成功响应。

HTTP/1.1 200 OK
Content-Type: application/json
{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}
Property Description
challenge_type 密码 在所需凭据的响应中返回。
continuation_token Microsoft Entra返回的延续标记。

重定向响应

如果客户端应用不支持Microsoft Entra要求的身份验证方法或功能,则需要回退到基于 Web 的身份验证流。 在此方案中,Microsoft Entra通过在响应中返回 redirect 质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "challenge_type": "redirect"
}
Property Description
challenge_type Microsoft Entra返回具有质询类型的响应。 此质询类型的值为 redirect,该值可让应用使用基于 Web 的身份验证流。

虽然此响应视为成功响应,但应用需要切换到基于 Web 的身份验证流。 这种情况下,建议使用 Microsoft 构建和支持的身份验证库。

步骤 4:进行身份验证并获取用于注册的令牌

应用需要提交用户凭据(在本例中为密码)Microsoft Entra在上一步中请求。 如果应用未通过 /signup/v1.0/start 终结点提交密码凭据,则需要提交密码凭据。 应用向 /signup/v1.0/continue 终结点发出提交密码的请求。 由于我们要提交密码,因此需要 password 参数,并且 grant_type 参数必须具有值“密码”。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=password
&password={secure_password}
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
continuation_token 是的 上一步中返回Microsoft Entra的延续标记。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
grant_type 是的 可以使用对 /signup/v1.0/continue 终结点的请求提交一次性密码、密码或使用用户属性。 这种情况下,grant_type 值用于区分这三种用例。 grant_type 可能的值有oob、密码、属性。 在此调用中,由于发送的是用户的密码,该值应为“密码”。
password 是的 应用从客户用户处收集到的密码值。 将 {secure_password} 替换为应用从客户用户处收集到的密码值。 你有责任通过提供应用 UI 中的密码确认字段来确认用户想要使用的密码。 还必须确保用户知道根据组织策略构成强密码的内容。 详细了解Microsoft Entra的密码策略。

成功响应

如果请求成功,但在Microsoft Entra管理中心中未配置任何属性,或者所有必需的属性都通过 /signup/v1.0/start 终结点提交,则应用将获取延续令牌而不提交任何属性。 应用可以使用延续令牌请求安全令牌,如 安全令牌请求中所示。 否则,Microsoft Entra的响应指示应用需要提交所需的属性。 租户管理员在Microsoft Entra管理中心配置了这些属性(内置或自定义)。

所需的用户属性

此响应请求应用提交 名称、 年龄和 电话 属性的值。

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "attributes_required",
    "error_description": "User attributes required",
    "error_codes": [
            55106
        ],
    "timestamp": "yy-mm-dd 02:37:33Z",
    "trace_id": "d6966055-...-80500",
    "correlation_id": "3944-...-60d6",
    "continuation_token": "AQABAAEAAAAtn...",
    "required_attributes": [
        {
            "name": "displayName",
            "type": "string",
            "required": true,
            "options": {
              "regex": ".*@.**$"
            }
        },
        {
            "name": "extension_2588abcdwhtfeehjjeeqwertc_age",
            "type": "string",
            "required": true
        },
        {
            "name": "postalCode",
            "type": "string",
            "required": true,
            "options": {
              "regex":"^[1-9][0-9]*$"
            }
        }
    ]
}

Note

自定义属性(也称为目录扩展)使用约定 extension_{appId-without-hyphens}_{attribute-name} 进行命名,其中 {appId-without-hyphens} 是扩展应用客户端 ID 的剥离版本。 例如,如果扩展应用的客户端 ID 为 2588a-bcdwh-tfeehj-jeeqw-ertc,且属性名称为爱好,则自定义属性被命名为 extension_2588abcdwhtfeehjjeeqwertc_hobbies。 详细了解自定义属性和扩展应用。

Property Description
error 如果Microsoft Entra无法创建用户帐户,则设置此属性,因为需要验证或提交属性。
error_description 可帮助用户识别错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。
continuation_token Microsoft Entra返回的延续标记。
required_attributes 应用需要提交下次调用才能继续的属性列表(一组对象)。 这些属性是除了用户名以外,应用还需要提交的其他属性。 如果 error 参数的值attributes_required,则Microsoft Entra包含此参数是响应。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,延续令牌验证失败或请求未包含 client_id 参数,导致客户端 ID 为空或无效。
invalid_grant 请求中包含的授权类型无效或不受支持。 grant_type 可能出现的值有 oob、密码、属性
expired_token 请求中包含的延续令牌已过期。
attributes_required 一个或多个用户属性是必需的。

重定向响应

如果客户端应用不支持Microsoft Entra要求的身份验证方法或功能,则需要回退到基于 Web 的身份验证流。 在此方案中,Microsoft Entra通过在响应中返回 redirect 质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Property Description
challenge_type Microsoft Entra返回具有质询类型的响应。 此质询类型的值为 redirect,该值可让应用使用基于 Web 的身份验证流。

虽然此响应视为成功响应,但应用需要切换到基于 Web 的身份验证流。 这种情况下,建议使用 Microsoft 构建和支持的身份验证库。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_grant",
    "error_description": "New password is too weak",
    "error_codes": [
        399246
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "suberror": "password_too_weak"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。
suberror 错误代码字符串,可用于对错误类型进行进一步分类。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,当 challenge_type 参数包含无效的质询类型。
invalid_grant 提交的授权无效,例如提交的密码太短。 使用该 suberror 属性可了解错误的确切原因。
expired_token 延续令牌已过期。
attributes_required 一个或多个用户属性是必需的。

如果错误参数的值为 invalid_grant,则Microsoft Entra在其响应中包含 suberror 属性。 下面是属性的 suberror 可能值:

Suberror 值 Description
password_too_weak 密码太弱,因为它不符合复杂性要求。 详细了解Microsoft Entra的密码策略。
password_too_short 新密码少于 8 个字符。 详细了解Microsoft Entra的密码策略。
password_too_long 新密码长度超过 256 个字符。 详细了解Microsoft Entra的密码策略。
password_recently_used 新密码不得与最近使用的密码相同。 详细了解Microsoft Entra的密码策略。
password_banned 新密码包含禁止的单词、短语或模式。 详细了解Microsoft Entra的密码策略。
password_is_invalid 密码无效,例如,因为它使用不允许的字符。 详细了解Microsoft Entra的密码策略。 如果应用提交用户密码,则此响应可能。

提交用户属性

应用需要调用 /signup/v1.0/continue 终结点提交必需的用户属性,流才能继续进行。 由于提交的是属性,需要 attributes 参数,且 grant_type 参数的值必须等于属性。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue
Content-Type: application/x-www-form-urlencoded
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=attributes
&attributes={"displayName": "{given_name}", "extension_2588abcdwhtfeehjjeeqwertc_age": "{user_age}", "postalCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
grant_type 是的 可以使用对 /signup/v1.0/continue 终结点的请求提交一次性密码、密码或使用用户属性。 这种情况下,grant_type 值用于区分这三种用例。 grant_type 可能的值有oob、密码、属性。 在本次调用中,由于发送的是用户属性,该值预期为属性。
attributes 是的 应用从客户用户处收集到的用户属性值。 该值是字符串,但采用 JSON 对象格式,其键值是用户属性的名称(无论是内置还是自定义)。 对象的键名称取决于管理员在Microsoft Entra管理中心配置的属性。 将{given_name}、{user_age}、{postal_code}分别替换为应用从客户用户处收集到的姓名、年龄和邮政编码值。 Microsoft Entra忽略提交的任何属性,这些属性不存在。

成功响应

如果请求成功,Microsoft Entra注册用户,然后颁发延续令牌。 应用可以使用延续令牌从 oauth/v2.0/token 终结点请求安全令牌。

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "AQABAAEAAAYn..."
}
Property Description
continuation_token Microsoft Entra返回的延续标记。

重定向响应

如果客户端应用不支持Microsoft Entra要求的身份验证方法或功能,则需要回退到基于 Web 的身份验证流。 在此方案中,Microsoft Entra通过在响应中返回 redirect 质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Property Description
challenge_type Microsoft Entra返回具有质询类型的响应。 此质询类型的值为 redirect,该值可让应用使用基于 Web 的身份验证流。

虽然此响应视为成功响应,但应用需要切换到基于 Web 的身份验证流。 这种情况下,建议使用 Microsoft 构建和支持的身份验证库。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "expired_token",
    "error_description": "AADSTS901007: The continuation_token is expired.  .\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        552003
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。
continuation_token Microsoft Entra返回的延续标记。
unverified_attributes 必须验证的属性键名称列表(一组对象)。 当 error 参数的值为 verification_required 时,响应中包含此参数。
required_attributes 应用需要提交的属性列表(一组对象)。 当 error 参数的值attributes_required时,Microsoft Entra在响应中包含此参数。
invalid_attributes 未通过验证的属性列表(一组对象)。 当属性的值suberror时,该参数包含在响应中。
suberror 错误代码字符串,可用于对错误类型进行进一步分类。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,延续令牌验证失败或请求未包含 client_id 参数,导致客户端 ID 为空或无效。
invalid_grant 提供的授权类型无效或不受支持或验证失败,例如属性验证失败。 使用该 suberror 属性可了解错误的确切原因。
expired_token 请求中包含的延续令牌已过期。
attributes_required 一个或多个用户属性是必需的。

如果错误参数的值为 invalid_grant,则Microsoft Entra在其响应中包含 suberror 属性。 下面是suberror错误的属性的可能值:

Suberror 值 Description
attribute_validation_failed 用户属性验证失败。 invalid_attributes 参数包含验证失败的属性的列表(对象数组)。

步骤 5:注册后自动登录

如果用户必须在注册后自动登录,应用会向 oauth/v2.0/token 终结点发出 POST 请求,并提供从上一步获取的延续令牌来获取安全令牌。 了解如何调用令牌终结点。

将用户属性提交到终结点

在Microsoft Entra管理中心,可以根据需要或可选配置用户属性。 此配置确定在调用其终结点时Microsoft Entra响应的方式。 可选属性对于完成注册流不是必需的。 因此,当所有属性都是可选内容时,必须先提交它们,然后才能验证用户名。 否则,注册无需可选属性即可完成。

下表汇总了将用户属性提交到Microsoft Entra终结点的可能时间。

Endpoint 必需属性 可选属性 必需属性和可选属性
/signup/v1.0/start endpoint 是的 是的 是的
/signup/v1.0/continue 用户名验证前的终结点 是的 是的 是的
/signup/v1.0/continue 用户名验证后的终结点 是的 No 是的

用户属性值的格式

通过在Microsoft Entra管理中心配置用户流设置,指定要从用户收集的信息。 查看在注册过程中收集自定义用户属性一文,了解如何收集内置和自定义两种属性的值。

还可以为你配置的属性指定用户输入类型。 下表总结了受支持的用户输入类型,以及如何将 UI 控件收集的值提交到Microsoft Entra。

用户输入类型 提交的值的格式
文本框  职务、软件工程师等单个值。
SingleRadioSelect 语言、挪威语等单个值。 
CheckboxMultiSelect 跳舞或跳舞、游泳、旅行等爱好,这样的一个或多个值。

以下请求示例演示了如何提交属性的值:

POST /{tenant_subdomain}.onmicrosoft.com/signup/v1.0/continue HTTP/1.1
Host: {tenant_subdomain}.ciamlogin.com
Content-Type: application/x-www-form-urlencoded
 
continuation_token=ABAAEAAAAtfyo... 
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=attributes 
&attributes={"jobTitle": "Software Engineer", "extension_2588abcdwhtfeehjjeeqwertc_language": "Norwegian", "extension_2588abcdwhtfeehjjeeqwertc_hobbies": "Dancing,Swimming,Traveling"}
&continuation_token=AQABAAEAAAAtn...

请参阅自定义用户属性输入类型一文,详细了解用户属性输入类型。

如何引用用户属性

创建注册用户流时,要配置要在注册过程中从用户收集的用户属性。 Microsoft Entra 管理中心中用户属性的名称与在本机身份验证 API 中引用它们的方式不同。

例如,Microsoft Entra管理中心中的 Display Name 在 API 中引用为 displayName。

使用 用户配置文件属性 文章了解如何在本机身份验证 API 中引用内置用户属性和自定义用户属性。

登录流程的API参考

用户需要使用用于注册的身份验证方法登录。 例如,使用具有密码身份验证方法的电子邮件注册的用户必须使用电子邮件和密码登录。

若要请求安全令牌,应用与三个终结点、oauth/v2.0/initiate、oauth/v2.0/challengeoauth/v2.0/token和(可选)oauth/v2.0/introspect交互。

登录API端点

Endpoint Description
oauth/v2.0/initiate 此终结点启动登录流。 如果你的应用使用已存在的用户帐户的用户名调用它,它将返回包含延续令牌的成功响应。 如果你的应用请求使用Microsoft Entra不支持的身份验证方法,则此终结点响应可以向应用指示它需要使用基于浏览器的身份验证流。
oauth/v2.0/challenge 应用调用此终结点以请求Microsoft Entra,以选择支持登录质询类型之一供用户进行身份验证。 如果租户管理员对客户用户强制实施 MFA,应用会调用此终结点来质询用户采用第二因素身份验证方法。
oauth/v2.0/token 此终结点验证从应用收到的用户的凭据,然后将安全令牌颁发给应用。 此终结点的响应还可以指示用户是否需要完成 MFA 质询或注册强身份验证方法。
oauth/v2.0/introspect 应用调用它以请求多重身份验证的已注册强身份验证方法列表(MFA)。 了解如何使用内省终结点

登录质询类型

API 允许应用在调用Microsoft Entra时播发它支持的身份验证方法。 为此,应用会使用其请求中的 challenge_type 参数来进行播发。 此参数包含表示不同身份验证方法的预定义值。

对于给定的身份验证方法,应用在注册流期间发送到Microsoft Entra的挑战类型值与应用登录时相同。 例如,对于注册和登录流,具有密码身份验证方法的电子邮件使用oob、密码和重定向质询类型值。

请在本机身份验证质询类型一文中详细了解质询类型。

注册流协议详细信息

序列图演示了登录过程的流。 登录流取决于用户的身份验证方法。

本机身份验证登录与电子邮件一次性密码的关系图。

应用使用 OTP 验证用户电子邮件后,会收到安全令牌。 如果一次性密码送达延迟或未发送到用户电子邮件,则用户可以请求发送另一个一次性密码。 如果上一个密码尚未验证,Microsoft Entra重新发送另一个一次性密码。 当Microsoft Entra重新发送一次性密码时,它将使以前发送的代码失效。

在后续部分中,我们将登录流汇总为三个基本步骤。

步骤 1:请求开始登录流

身份验证流开始,应用向 /initiate 终结点发送 POST 请求,以开始登录流。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/initiate
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&username=contoso-consumer@contoso.com
&capabilities=registration_required mfa_required
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
username 是的 客户用户的电子邮件,例如 contoso-consumer@contoso.com。
challenge_type 是的 以空格分隔的应用支持的授权质询类型字符串列表,例如 oob password redirect。 列表中必须始终包含 redirect 质询类型。 对于电子邮件一次性密码,此值应为oob redirect,对于具有密码的电子邮件,此值应为password redirect。
capabilities No 描述客户端应用的“作方式”就绪情况的空间分隔标志。 虽然 challenge_type 定义了哪些方法可能受到质询, capabilities 但告诉本机身份验证 API 客户端应用可以处理哪些额外的流,以及它可以显示的 UI。 例如, mfa_required means /introspect和 /challenge/token loop;registration_required表示客户端应用调用注册 API 并显示注册 UI。 如果客户端应用不包含所需的功能,API 将返回重定向。 支持的值是 mfa_required 和 registration_required。 详细了解功能。

成功响应

下面是成功响应的示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
Property Description
continuation_token Microsoft Entra返回的延续标记。

重定向响应

如果客户端应用不支持Microsoft Entra要求的身份验证方法或功能,则需要回退到基于 Web 的身份验证流。 在此方案中,Microsoft Entra通过在响应中返回 redirect 质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "challenge_type": "redirect"
}
Property Description
challenge_type Microsoft Entra返回具有质询类型的响应。 此质询类型的值为 redirect,该值可让应用使用基于 Web 的身份验证流。

虽然此响应视为成功响应,但应用需要切换到基于 Web 的身份验证流。 这种情况下,建议使用 Microsoft 构建和支持的身份验证库。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,当 challenge_type 参数包含无效的质询类型。 或请求不包含 client_id 参数,客户端 ID 值为空或无效。 使用 error_description 参数了解错误的具体原因。
unauthorized_client 请求中使用的客户端 ID 的格式有效,但外部租户中不存在或不正确。
invalid_client 应用包含在请求中的客户端 ID 是供缺少本机身份验证配置的应用使用的,例如,不是公共客户端或未启用本机身份验证。 使用该 suberror 属性可了解错误的确切原因。
user_not_found 此用户名不存在。
unsupported_challenge_type challenge_type 参数值不包含 redirect 质询类型。

如果错误参数的值为 invalid_client,则Microsoft Entra在其响应中包含 suberror 属性。 下面是suberror错误的属性的可能值:

Suberror 值 Description
nativeauthapi_disabled 未启用本机身份验证的应用的客户端 ID。

步骤 2:选择身份验证方法

若要继续流,应用使用它从上一步获取的延续令牌来请求Microsoft Entra为用户选择一种受支持的质询类型,以便对 MFA 质询进行身份验证或完成 MFA 质询。 应用向 /oauth2/v2.0/challenge 终结点发出 POST 请求。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=password redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。 上一个请求调用 /oauth2/v2.0/initiate 终结点;如果用户完成 MFA 质询,则 /oauth2/v2.0/introspect 调用终结点。
challenge_type No 以空格分隔的应用支持的授权质询类型字符串列表,例如 oob password redirect。 列表中必须始终包含 redirect 质询类型。 对于电子邮件一次性密码,此值应为oob redirect,对于具有密码的电子邮件,此值应为password redirect。
id No 从终结点返回的强身份验证方法的 /oauth2/v2.0/introspect 字符串标识符。 当客户端应用质询用户进行第二重身份验证时,此参数是必需的。 了解如何使用内省终结点。

成功响应

成功响应取决于用户的身份验证方法。

如果租户管理员将Microsoft Entra管理中心的电子邮件一次性密码配置为用户的身份验证方法,Microsoft Entra向用户的电子邮件发送一次性密码,然后响应质询类型为 oob 并提供有关一次性密码的详细信息。

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ",
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}
Property Description
continuation_token Microsoft Entra返回的延续标记。
challenge_type 为用户进行身份验证所选择的质询类型。
binding_method 唯一的有效值为“prompt”。 将来可以使用此参数为用户提供更多输入一次性密码的方式。 如果 challenge_type 是 oob,则颁发
challenge_channel 发送一次性密码的通道的类型。 目前,我们支持电子邮件。
challenge_target_label 一封模糊的电子邮件,其中发送了一次性密码。
code_length Microsoft Entra生成的一次性密码的长度。

重定向响应

在以下情况下,可能需要回退到基于 Web 的身份验证流:

  • 客户端应用不支持Microsoft Entra要求的身份验证方法或功能。
  • 用户尝试使用短信作为强身份验证方法,但欺诈保护会阻止请求(仅电子邮件中具有密码身份验证)。

在这些方案中,Microsoft Entra通过在响应中返回 redirect 质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Property Description
challenge_type Microsoft Entra返回具有质询类型的响应。 此质询类型的值为 redirect,该值可让应用使用基于 Web 的身份验证流。

虽然此响应视为成功响应,但应用需要切换到基于 Web 的身份验证流。 这种情况下,建议使用 Microsoft 构建和支持的身份验证库。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,当 challenge_type 参数包含无效的质询类型。
invalid_grant 请求中包含的延续令牌无效。
expired_token 请求中包含的延续令牌已过期。
unsupported_challenge_type challenge_type 参数值不包含 redirect 质询类型。

步骤 3:请求安全令牌

应用向 oauth2/v2.0/token 终结点发出 POST 请求,并提供在上一步中选择的用户凭据来获取安全令牌。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444 
&grant_type=password 
&password={secure_password}
&scope=openid offline_access 
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。
grant_type 是的 授权类型。 调用令牌终结点时,此值必须为:
- 登录流中具有密码身份验证方法的电子邮件的密码,以验证用户的第一个因素身份验证。
- 登录流中电子邮件一次性密码身份验证方法的 oob。
- continuation_token 注册流后自动登录。
- continuation_token 自助密码重置流后自动登录。
- 在强身份验证方法注册流之后continuation_token。
- 验证用户的第二重身份验证时mfa_oob。
scope 是的 以空格分隔的作用域列表。 所有范围都必须来自单个资源,以及 OpenID Connect (OIDC) 范围,例如 配置文件、 openid 和 电子邮件。 应用需要包括 openid 范围,以便Microsoft Entra颁发 ID 令牌。 应用需要包括 offline_access 范围,以便Microsoft Entra颁发刷新令牌。 详细了解 Microsoft 标识平台中的权限和同意。
password No 应用从用户那里收集的密码值。 替换为 {secure_password} 应用从用户收集的密码值。 如果身份验证方法是包含密码的电子邮件, 则此参数是必需的 。
oob No 用户通过电子邮件接收的一次性密码。 必需条件:
- 主要身份验证方法是电子邮件一次性密码。
- 当主要身份验证方法是使用密码的电子邮件时,应用正在提交电子邮件一次性密码以满足 MFA 质询。
若要重新发送一次性密码,请再次调用 /challenge 终结点。
username No 要注册的用户的电子邮件,例如 contoso-consumer@contoso.com。 注册流中 需要 此参数。

成功的响应

下面是成功响应的示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "token_type": "Bearer",
    "scope": "openid profile",
    "expires_in": 4141,
    "access_token": "eyJ0eXAiOiJKV1Qi...",
    "refresh_token": "AwABAAAA...",
    "id_token": "eyJ0eXAiOiJKV1Q..."
}
Property Description
token_type 指示标记类型值。 Microsoft Entra支持的唯一类型是 Bearer。
scopes 一个空间分隔的范围列表,访问令牌有效。
expires_in 访问令牌保持有效的时间长度(以秒为单位)。
access_token 应用从 /token 终结点请求的访问令牌。 应用可以使用此访问令牌请求访问 Web API 等安全的资源。
refresh_token OAuth 2.0 刷新令牌。 应用可以使用此令牌,在当前访问令牌过期之后获取其他访问令牌。 刷新令牌的有效期较长。 它们可以长期保留对资源的访问权限。 有关刷新访问令牌的更多详细信息,请参阅 “刷新访问令牌”。
注意:仅当请求 offline_access 范围时才发出。
id_token 用于标识用户的 JSON Web 令牌(Jwt)。 应用可以解码此令牌,以请求已登录用户的相关信息。 应用可以缓存并显示值,机密客户端可以使用此令牌进行授权。 有关 ID 令牌的详细信息,请参阅 Microsoft标识平台中的 ID 令牌。
注意:仅当请求 openid 范围时才发出。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{ 
    "error": "invalid_grant", 
    "error_description": "AADSTS901007: Error validating credentials due to invalid username or password.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [ 
        50126 
    ], 
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333", 
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
} 
Property Description
error 错误代码字符串,可用于对错误类型进行分类和对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败。 使用错误描述中的消息了解发生了什么。
invalid_grant 请求中包含的延续令牌无效、请求中包含的用户登录凭据无效、用户所需的进一步交互或请求中包含的授权类型未知。
invalid_client 请求中包含的客户端 ID 不适用于公共客户端。
expired_token 请求中包含的延续令牌已过期。
invalid_scope 请求中包含的一个或多个范围无效。
unauthorized_client 请求中包含的客户端 ID 无效或不存在。
unsupported_grant_type 请求中包含的授权类型不受支持或不正确。

如果错误参数的值为 invalid_grant,则Microsoft Entra在其响应中包含 suberror 属性。 下面是suberror错误的属性的可能值:

Suberror 值 Description
invalid_oob_value 应用提交的一次性密码的值无效。
mfa_required MFA 是必需的。 响应包括 延续标记。 oauth2/v2.0/introspect调用终结点以获取用户的已注册强身份验证方法。 仅当用户的主要身份验证方法是使用密码的电子邮件时,才会发生此子程序。 了解如何 获取用户的已注册强身份验证方法。

注意:在某些情况下,需要 MFA,但本机身份验证不会返回 mfa_required。 或者,如果 强身份验证方法注册 流在调用 /oauth2/v2.0/token 之前,并且该流中已验证唯一可用的方法(电子邮件)。
registration_required 用户必须完成 MFA 质询,但没有注册的强身份验证方法。 提示用户注册一个。 当用户的主要身份验证方法是使用密码的电子邮件时,会发生此错误。 了解如何 注册强身份验证方法。

重定向响应

如果客户端应用不支持Microsoft Entra要求的身份验证方法或功能,则需要回退到基于 Web 的身份验证流。 在此方案中,Microsoft Entra通过在其响应中返回redirect质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json
{     
    "challenge_type": "redirect",
    "redirect_reason": "Client is missing registration_required capability"
} 
Property Description
challenge_type Microsoft Entra返回具有质询类型的响应。 此质询类型的值为 redirect,该值可让应用使用基于 Web 的身份验证流。
redirect_reason 需要重定向的原因。 例如,Microsoft Entra检测到需要 MFA 或强身份验证方法的注册,但应用在其请求中不包含这些功能。

虽然此响应视为成功响应,但应用需要切换到基于 Web 的身份验证流。 这种情况下,建议使用 Microsoft 构建和支持的身份验证库。

获取用户注册的强身份验证方法

oauth2/v2.0/introspect使用终结点请求用户已注册的强身份验证方法列表。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/introspect
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。

成功响应

示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"c***r@co**o**o.com"
        },
        {
          "id": "1b1b1b1b-2222-cccc-3333-4d4d4d4d4d4d",
          "challenge_type": "oob",
          "challenge_channel": "sms",
          "login_hint": "+1********6"
        }
    ]
}
Property Description
continuation_token Microsoft Entra返回的延续标记。
methods 用户注册的强身份验证方法的列表(对象)。

MFA 方法对象具有以下属性:

Property Description
id MFA 方法自动生成的唯一字符串标识符。 应用在调用id终结点时使用此字符串/oauth2/v2.0/challenge。
challenge_type 为用户选择的质询类型,以用作 MFA 方法。 当前支持的质询类型为 oob。
challenge_channel 将 MFA 方法发送到的通道的类型。 当前支持的挑战频道是 电子邮件。
login_hint 强身份验证方法(如模糊电子邮件)的提示。

重定向响应

如果客户端应用不支持Microsoft Entra要求的身份验证方法或功能,则需要回退到基于 Web 的身份验证流。 在此方案中,Microsoft Entra通过在响应中返回 redirect 质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        50126
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败。 使用错误描述中的消息了解发生了什么。
invalid_client 请求中包含的客户端 ID 不适用于公共客户端。
expired_token 请求中包含的延续令牌已过期。
server_error 请求出现问题。

客户端应用成功检索为用户注册的强身份验证方法列表后,用户将选择要用于完成 MFA 质询的方法。 然后,该流继续,如下所示:

  1. 客户端应用调用/oauth2/v2.0/challenge并包括从/oauth2/v2.0/introspectid所选 MFA 方法获取的延续令牌:

    POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/challenge
    Content-Type: application/x-www-form-urlencoded
    client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &id=0a0a0a0a-1111-bbbb-2222-3c3c3c3c3c3c
    &continuation_token=uY29tL2F1dGhlbnRpY...
    
  2. Microsoft Entra向用户的挑战通道(例如电子邮件)发送质询代码,然后使用延续令牌和 MFA 质询详细信息回复客户端应用:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "continuation_token": "uY29tL2F1dGhlbnRpY...",
        "challenge_type": "oob",
        "binding_method": "prompt ",
        "challenge_channel": "email",
        "challenge_target_label ": "c***r@co**o**o.com ",
        "code_length": 8
    }
    
  3. 应用现在可以向 /oauth2/v2.0/token 终结点发出 POST 请求,并包括延续令牌、正确的授权类型和相应的授予类型值来获取安全令牌。 请参阅 请求安全令牌中的预期响应:

    POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/oauth2/v2.0/token
    Content-Type: application/x-www-form-urlencoded
    client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &continuation_token=uY29tL2F1dGhlbnRpY...
    &grant_type=mfa_oob
    &oob={otp_code}
    &scope=openid offline_access
    

注册强身份验证方法 API 参考

本机身份验证支持注册强身份验证方法。 当应用调用 /oauth2/v2.0/token 终结点和 MFA 时,用户没有注册的强方法,响应 registration_required指示应用在颁发令牌之前注册一个令牌。

客户端应用完成流以注册强身份验证方法后,它会调用 /oauth2/v2.0/token 终结点来请求安全令牌。

强身份验证方法注册终结点

若要使用强身份验证方法注册 API,应用使用下表所示的终结点:

Endpoint Description
/register/v1.0/introspect 调用此终结点可提取用户可注册的强身份验证方法列表。
/register/v1.0/challenge 调用此终结点以向用户发送质询,例如电子邮件一次性密码。
/register/v1.0/continue 调用此终结点以提交应用从用户(如一次性密码)收集的挑战,以完成流以注册强身份验证方法。 调用成功并获取延续令牌后,调用 /oauth2/v2.0/token 终结点以请求安全令牌。 了解如何调用令牌终结点。

步骤 1:获取强身份验证方法的列表

注册流在应用请求用户允许注册的强身份验证方法列表时开始。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/introspect
Content-Type: application/x-www-form-urlencoded
?continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。

成功响应

下面是成功响应的示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "methods":[
        {
            "id":"email",
            "challenge_type":"oob",
            "challenge_channel":"email",
            "login_hint":"caseyjensen@contoso.com"
        },
        {
          "id": "sms",
          "challenge_type": "oob",
          "challenge_channel": "sms"
        }
    ]
}
Property Description
continuation_token Microsoft Entra返回的延续标记。
methods 可供用户注册的强身份验证方法的列表(对象)。

强身份验证方法对象具有以下属性:

Property Description
id 方法的字符串键。 支持的值 电子邮件、短信。
challenge_type 为用户选择的质询类型,以用作 MFA 方法。 当前支持的质询类型为 oob。
challenge_channel 将 MFA 方法发送到的通道的类型。 支持的值 电子邮件、短信。
login_hint 强身份验证方法(如电子邮件)的提示。 客户端应用使用此值来预填充电子邮件文本框。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The continuation_token provided is not valid for this endpoint.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        50126
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,延续令牌验证失败或请求未包含 client_id 参数,导致客户端 ID 为空或无效,或者外部租户管理员并未给所有租户用户都启用电子邮件 OTP 租户。
expired_token 请求中包含的延续令牌已过期。

步骤 2:选择强身份验证方法

在此步骤中,提交用户希望注册的强身份验证方法。 然后,Microsoft Entra向用户发送质询,例如电子邮件一次性密码。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/challenge

?continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob
&challenge_channel=email
&challenge_target=contoso-consumer@contoso.com
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
continuation_token 是的 Microsoft Entra从 终结点返回的 /register/v1.0/introspect
challenge_type 是的 身份验证方法的质询类型。 当前类型为 oob。
challenge_target 是的 用户想要注册的电子邮件或电话号码。
challenge_channel No 要发送挑战的通道。 支持的质询通道值: 电子邮件、短信。

成功响应

下面是成功响应的示例。

示例 1:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "oob",
  "binding_method": "prompt",
  "challenge_target": "contoso-consumer@contoso.com",
  "challenge_channel": "email",
  "code_length": 8
}

示例 2:

如果注册流位于强身份验证方法注册流之前,并且提交到 /register/v1.0/challenge 终结点的电子邮件与注册流中验证的电子邮件匹配,则本机身份验证 API 会注册该方法,而不会向用户发送质询。 在这种情况下,响应将类似于以下代码片段:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "continuation_token": "uY29tL2F1dGhlbnRpY...",
  "challenge_type": "preverified"
}
Property Description
continuation_token Microsoft Entra返回的延续标记。
challenge_type 为用户选择的质询类型(例如 oob)进行身份验证;如果强身份验证方法得到 preverified ,则为用户选择质询类型。
binding_method 唯一的有效值为“prompt”。 将来可以使用此参数为用户提供更多输入一次性密码的方式。 如果 challenge_type 为 oob 且强身份验证方法未被预报,则颁发。
challenge_channel 发送一次性密码的通道的类型。 支持的值 电子邮件、短信。 如果未验证强身份验证方法,则返回。
code_length 出现提示时 binding_method ,一次性密码的长度。 如果未验证强身份验证方法,则返回。
challenge_target 挑战的目标被发送到。 这与请求中提供的输入相同。 如果未验证强身份验证方法,则返回。
interval 客户端应在轮询 /register/continue 之间等待的间隔(以秒为单位)。 仅当强身份验证方法未经过验证时才返回 prompt=none 。 客户端每次从本机身份验证 API 收到 HTTP 429 间隔时应加倍。

错误响应

此处的错误类似于调用 /register/v1.0/introspect 终结点时可能会遇到的错误。 但是,注册电话号码时,如果电话号码被视为高风险,可能会阻止请求。

下面是在阻止请求时可能会遇到的可能错误:

误差值 Description
access_denied 短信已被阻止。

如果错误参数的值为 access_denied,则Microsoft Entra在其响应中包含子error 属性。 下面是invalid_grant错误的子error 属性的可能值:

Suberror 值 Description
provider_blocked_by_admin 租户管理员已阻止电话区域。
provider_blocked_by_rep 多重身份验证方法被阻止(电话号码被 RepMap 阻止)。

步骤 3:提交质询

在此步骤中 /register/v1.0/continue ,调用终结点以完成强身份验证方法的注册。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/register/v1.0/continue

?continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
grant_type 是的 授权类型。 当前支持的值是 oob,或者 如果 强身份验证方法在终结点中 /register/v1.0/challenge 得到 preverified,则continuation_token。
oob No 客户用户在其电子邮件中收到的一次性密码。 将{otp_code}替换为客户用户在其电子邮件中收到的一次性密码值。 要重新发送一次性密码,应用需要再次向 /register/v1.0/challenge 终结点发出请求。 如果在终结点中未预取强身份验证方法, /register/v1.0/challenge 则为必需。

成功响应

下面是成功响应的示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
Property Description
continuation_token Microsoft Entra返回的 continuation 标记。 使用此延续令牌调用 /oauth2/v2.0/token 终结点以请求安全令牌。 了解如何调用令牌终结点。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        55200
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,延续令牌验证失败或请求未包含 client_id 参数,导致客户端 ID 为空或无效,或者外部租户管理员并未给所有租户用户都启用电子邮件 OTP 租户。
invalid_grant 请求中包含的授权类型无效或不受支持,或者 OTP 值不正确。
expired_token 请求中包含的延续令牌已过期。

如果错误参数的值为 invalid_grant,则Microsoft Entra在其响应中包含 suberror 属性。 下面是suberror错误的属性的可能值:

Suberror 值 Description
invalid_oob_value 一次性密码的值无效。

自助式密码重置 (SSPR)

对于主要身份验证方法是使用密码发送电子邮件的用户,请使用自助密码重置 (SSPR) API 使客户用户能够重置其密码。 可以将此 API 用于忘记密码或更改密码方案。

自助密码重置的API端点

若要使用此 API,应用使用下表中所示的终结点:

Endpoint Description
/resetpassword/v1.0/start 当客户用户选择应用中的“忘记密码”或“更改密码”链接或按钮时,应用将调用此终结点。 此终结点验证用户的用户名(电子邮件),然后返回要在密码重置流中使用的 延续令牌 。 如果你的应用请求使用Microsoft Entra不支持的身份验证方法,则此终结点响应可以向应用指示它需要使用基于浏览器的身份验证流。
/resetpassword/v1.0/challenge 接受客户端支持的质询类型列表和延续令牌。 向首选恢复凭据之一颁发质询。 例如,oob 质询向与客户用户帐户关联的电子邮件发出带外一次性密码代码。 如果你的应用请求使用Microsoft Entra不支持的身份验证方法,则此终结点响应可以向应用指示它需要使用基于浏览器的身份验证流。
/resetpassword/v1.0/continue 验证 /resetpassword/v1.0/challenge 终结点颁发的质询,然后为 终结点返回延续令牌/resetpassword/v1.0/submit,或向用户发出另一个质询。
/resetpassword/v1.0/submit 接受用户输入的新密码以及延续令牌,以完成密码重置流。 此终结点颁发另一个延续令牌。
/resetpassword/v1.0/poll_completion 应用可以使用终结点颁发的/resetpassword/v1.0/submit来检查密码重置请求的状态。
oauth2/v2.0/token 如果密码重置成功,应用可以使用它从 /resetpassword/v1.0/poll_completion 终结点获取的延续令牌从 oauth2/v2.0/token 终结点获取安全令牌。

自助式密码重置质询类型

API 允许应用在调用Microsoft Entra时播发它支持的身份验证方法。 为此,应用会使用其请求中的 challenge_type 参数来进行播发。 此参数包含表示不同身份验证方法的预定义值。

对于 SSPR 流,质询类型值为 oob 和 redirect。

请在本机身份验证质询类型中详细了解质询类型。

自助式密码重置流协议流

序列图演示了密码重置过程的流。

本机身份验证自助密码重置流示意图。

此图表明应用在不同时间(可能在不同的屏幕上)从用户收集用户名(电子邮件)和密码。 但是,你可以设计应用,以在同一屏幕上收集用户名(电子邮件)和新密码。 在本例中,应用保存密码,然后通过 /resetpassword/v1.0/submit 终结点提交密码。

步骤 1:请求开始自助式密码重置流

密码重置流从向 /resetpassword/v1.0/start 终结点发出 POST 请求的应用开始,以启动自助式密码重置流。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/start
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&username=contoso-consumer@contoso.com
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
username 是的 客户用户的电子邮件,例如 contoso-consumer@contoso.com。
challenge_type 是的 以空格分隔的应用支持的授权质询类型字符串列表,例如 oob password redirect。 列表中必须始终包含 redirect 质询类型。 对于此请求,该值应包含 oob redirect。
capabilities No 描述客户端应用的“作方式”就绪情况的空间分隔标志。 虽然 challenge_type 定义了哪些方法可能受到质询, capabilities 但告诉本机身份验证 API 客户端应用可以处理哪些额外的流,以及它可以显示的 UI。 例如, mfa_required 表示另一个 /challenge 和 /token 循环; registration_required 表示客户端应用调用注册 API 并显示注册 UI。 如果客户端应用未播发所需的功能,API 将返回重定向。 支持的值是 mfa_required 和 registration_required。 详细了解功能。

成功响应

示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}
Property Description
continuation_token Microsoft Entra返回的延续标记。

重定向响应

如果客户端应用不支持Microsoft Entra要求的身份验证方法或功能,则需要回退到基于 Web 的身份验证流。 在此方案中,Microsoft Entra通过在响应中返回 redirect 质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Property Description
challenge_type Microsoft Entra返回具有质询类型的响应。 此质询类型的值为 redirect,该值可让应用使用基于 Web 的身份验证流。

虽然此响应视为成功响应,但应用需要切换到基于 Web 的身份验证流。 这种情况下,建议使用 Microsoft 构建和支持的身份验证库。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,当 challenge_type 参数包含无效的质询类型,或请求未包含 client_id 参数,导致客户端 ID 值为空或无效。 使用 error_description 参数了解错误的具体原因。
user_not_found 此用户名不存在。
unsupported_challenge_type challenge_type 参数值不包含 redirect 质询类型。
invalid_client 应用包含在请求中的客户端 ID 是供缺少本机身份验证配置的应用使用的,例如,不是公共客户端或未启用本机身份验证。 使用该 suberror 属性可了解错误的确切原因。
unauthorized_client 请求中使用的客户端 ID 的格式有效,但外部租户中不存在或不正确。

如果错误参数的值为 invalid_client,则Microsoft Entra在其响应中包含 suberror 属性。 下面是suberror错误的属性的可能值:

Suberror 值 Description
nativeauthapi_disabled 未为本机身份验证启用的应用的客户端 ID。

步骤 2:选择身份验证方法

若要继续流,应用使用上一步获取的延续令牌来请求Microsoft Entra为用户选择一种受支持的质询类型,以便用户进行身份验证。 应用向 /resetpassword/v1.0/challenge 终结点发出 POST 请求。 如果此请求成功,Microsoft Entra向用户帐户电子邮件发送一次性密码。 目前,我们仅支持电子邮件 OTP。

下面是示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/challenge
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。
challenge_type No 以空格分隔的应用支持的授权质询类型字符串列表,例如 oob redirect。 列表中必须始终包含 redirect 质询类型。 对于此请求,该值应包含 oob redirect。

成功响应

示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "challenge_type": "oob",
    "binding_method": "prompt ",
    "challenge_channel": "email",
    "challenge_target_label ": "c***r@co**o**o.com ",
    "code_length": 8
}
Property Description
continuation_token Microsoft Entra返回的延续标记。
challenge_type 为用户进行身份验证所选择的质询类型。
binding_method 唯一的有效值为“prompt”。 将来可以使用此参数为用户提供更多输入一次性密码的方式。 如果 challenge_type 是 oob,则颁发
challenge_channel 发送一次性密码的通道的类型。 目前,我们支持电子邮件。
challenge_target_label 一封模糊的电子邮件,其中发送了一次性密码。 如果用户启用了 MFA,则包含一次性密码的电子邮件将发送到:
- 电子邮件地址与帐户电子邮件地址不同时用作强身份验证方法的电子邮件地址。
- 当强身份验证方法为 SMS 时,帐户电子邮件地址。
code_length Microsoft Entra生成的一次性密码的长度。

重定向响应

如果客户端应用不支持Microsoft Entra要求的身份验证方法或功能,则需要回退到基于 Web 的身份验证流。 在此方案中,Microsoft Entra通过在响应中返回 redirect 质询类型来通知应用:

HTTP/1.1 200 OK
Content-Type: application/json
{
   "challenge_type": "redirect"
}
Property Description
challenge_type Microsoft Entra返回具有质询类型的响应。 此质询类型的值为 redirect,该值可让应用使用基于 Web 的身份验证流。

虽然此响应视为成功响应,但应用需要切换到基于 Web 的身份验证流。 这种情况下,建议使用 Microsoft 构建和支持的身份验证库。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,当 challenge_type 参数包含无效的质询类型或延续令牌验证失败。
expired_token 延续令牌已过期。
unsupported_challenge_type challenge_type 参数值不包含 redirect 质询类型。

步骤 3:提交一次性密码

然后应用向 /resetpassword/v1.0/continue 终结点发出 POST 请求。 在请求中,应用需要包括在上一步中选择的用户凭据以及从 /resetpassword/v1.0/challenge 终结点颁发的延续令牌。

下面是请求示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/continue
Content-Type: application/x-www-form-urlencoded
continuation_token=uY29tL2F1dGhlbnRpY...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&grant_type=oob
&oob={otp_code}
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
grant_type 是的 唯一的有效值为 oob。
oob 是的 客户用户在其电子邮件中收到的一次性密码。 将 {otp_code} 替换为客户用户在其电子邮件中收到的一次性密码。 要重新发送一次性密码,应用需要再次向 /resetpassword/v1.0/challenge 终结点发出请求。

成功响应

示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW..."
}
Property Description
expires_in continuation_token 过期前的时间(以秒为单位)。 expires_in 的最大值为 600 秒。
continuation_token Microsoft Entra返回的延续标记。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS55200: The continuation_token is invalid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        55200
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。
suberror 错误代码字符串,可用于对错误类型进行进一步分类。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如,延续令牌验证失败或请求未包含 client_id 参数,导致客户端 ID 为空或无效,或者外部租户管理员并未给所有租户用户都启用 SSPR 和电子邮件 OTP 租户。 使用 error_description 参数了解错误的具体原因。
invalid_grant 授权类型未知或与预期的授予类型值不匹配。 使用该 suberror 属性可了解错误的确切原因。
expired_token 延续令牌已过期。

如果错误参数的值为 invalid_grant,则Microsoft Entra在其响应中包含 suberror 属性。 下面是suberror错误的属性的可能值:

Suberror 值 Description
invalid_oob_value 一次性密码的值无效。

步骤 4:提交新密码

应用从用户那里收集新密码,然后使用 终结点颁发的延续令牌/resetpassword/v1.0/continue向 /resetpassword/v1.0/submit 终结点发出 POST 请求来提交密码。

下面是示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/submit
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0Mzp...
&new_password={new_password}
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。
new_password 是的 用户的新密码。 将 {new_password} 替换为用户的新密码。 你有责任通过提供应用 UI 中的密码确认字段来确认用户想要使用的密码。 还必须确保用户知道根据组织策略构成强密码的内容。 详细了解Microsoft Entra的密码策略。

成功响应

示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}
Property Description
continuation_token Microsoft Entra返回的延续标记。
poll_interval 应用在轮询请求之间通过 /resetpassword/v1.0/poll_completion 终结点检查密码重置请求的状态应等待的最短时间(以秒为单位),请参阅步骤 5

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "invalid_request",
    "error_description": "AADSTS901007: The challenge_type list parameter does not include the 'redirect' type.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        901007
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。
suberror 错误代码字符串,可用于对错误类型进行进一步分类。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如延续令牌验证失败。
expired_token 延续令牌已过期。
invalid_grant 提交的授权无效,例如提交的密码太短。 使用该 suberror 属性可了解错误的确切原因。

如果错误参数的值为 invalid_grant,则Microsoft Entra在其响应中包含 suberror 属性。 下面是属性的 suberror 可能值:

Suberror 值 Description
password_too_weak 密码太弱,因为它不符合复杂性要求。 详细了解Microsoft Entra的密码策略。
password_too_short 新密码少于 8 个字符。 详细了解Microsoft Entra的密码策略。
password_too_long 新密码长度超过 256 个字符。 详细了解Microsoft Entra的密码策略。
password_recently_used 新密码不得与最近使用的密码相同。 详细了解Microsoft Entra的密码策略。
password_banned 新密码包含禁止的单词、短语或模式。 详细了解Microsoft Entra的密码策略。
password_is_invalid 密码无效,例如,因为它使用不允许的字符。 详细了解Microsoft Entra的密码策略。 如果应用提交用户密码,则此响应可能。

步骤 5:轮询密码重置状态

最后,由于使用新密码更新用户的配置会产生一些延迟,因此应用可以使用 /resetpassword/v1.0/poll_completion 终结点轮询Microsoft Entra以查找密码重置状态。 应用应在轮询请求之间等待的最短时间(以秒为单位)从 /resetpassword/v1.0/submit 参数中的 poll_interval 终结点返回。

下面是示例(为方便查看,我们用多行展示该示例):

POST https://{tenant_subdomain}.ciamlogin.com/{tenant_subdomain}.onmicrosoft.com/resetpassword/v1.0/poll_completion
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&continuation_token=czZCaGRSa3F0...
Parameter 必填 Description
tenant_subdomain 是的 你创建的外部租户的子域。 在 URL 中,将 {tenant_subdomain} 替换为目录(租户)子域。 例如,如果租户的主域为 contoso.onmicrosoft.com,则使用 contoso。 如果没有租户子域,请了解如何读取租户详细信息。
continuation_token 是的 Microsoft Entra在上一个请求中返回的延续标记。
client_id 是的 在Microsoft Entra管理中心注册的应用的应用程序(客户端)ID。

成功响应

示例:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
}
Property Description
status 重置密码请求的状态。 如果Microsoft Entra返回状态为 failed,则应用可以通过向 /resetpassword/v1.0/submit 终结点发出另一个请求来重新提交新密码,并包括新的延续令牌。
continuation_token Microsoft Entra返回的延续标记。 如果状态为 ucceeded,则应用可以使用Microsoft Entra返回的延续令牌通过 oauth2/v2.0/token 终结点请求安全令牌,如安全令牌中所述。 这意味着,用户成功重置其密码后,无需启动新的登录流,即可直接登录到应用。

下面是Microsoft Entra返回的可能状态(status 参数的可能值):

误差值 Description
succeeded 密码重置成功完成。
failed 密码重置失败。 应用可以通过向 /resetpassword/v1.0/submit 终结点发出另一个请求来重新提交新密码。
not_started 密码重置尚未启动。 应用可以以后再次检查状态。
in_progress 密码重置正在进行中。 应用可以以后再次检查状态。

错误响应

示例:

HTTP/1.1 400 Bad Request
Content-Type: application/json
{
    "error": "expired_token",
    "error_description": "AADSTS901007: The continuation_token is expired.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: yyyy-...",
    "error_codes": [
        552003
    ],
    "timestamp": "yyyy-mm-dd 10:15:00Z",
    "trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
    "correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
Property Description
error 一个错误代码字符串,可用于对错误类型进行分类并对错误做出反应。
error_description 可帮助用户识别身份验证错误原因的特定错误消息。
error_codes 特定于Microsoft Entra错误代码的列表,可帮助你诊断错误。
timestamp 发生错误的时间。
trace_id 帮助诊断错误的请求唯一标识符。
correlation_id 用于该请求的唯一标识符,可帮助跨组件进行诊断。

下面是可能会遇到的错误(属性的 error 可能值):

误差值 Description
invalid_request 请求参数验证失败,例如延续令牌验证失败。
expired_token 延续令牌已过期。

密码重置后自动登录

如果用户需要在密码重置成功后登录。 应用需要调用 /oauth2/v2.0/token 终结点。 了解如何调用令牌终结点。