本机身份验证 API 参考
适用于：
员工租户 
外部租户（了解详细信息）
Microsoft Entra 的本机身份验证使你可以在客户端应用程序中托管应用的用户界面，而不是将身份验证委托给浏览器，从而带来本机集成的身份验证体验。 作为开发人员，你可以完全控制登录界面的外观。
此 API 参考文章介绍了仅当你手动发送原始 HTTP 请求以执行流时必需的详细信息。 但是，我们不建议采用这种方法。 因此，如果条件允许，请使用 Microsoft 构建和支持的身份验证 SDK。 要详细了解如何使用 SDK，请参阅教程：准备 Android 移动应用以进行本机身份验证和教程：准备 iOS/macOS 移动应用以进行本机身份验证。
成功调用 API 端点时，会同时收到用于用户身份验证的 ID 令牌和用于调用受保护的 API 的访问令牌。 来自 API 的所有响应均采用 JSON 格式。
Microsoft Entra 的本机身份验证 API 支持两种身份验证方法的注册和登录：
电子邮件和密码，它支持使用电子邮件和密码进行注册和登录，以及自助式密码重置 (SSPR)。
电子邮件一次性验证码，支持使用电子邮件一次性密码进行注册和登录。
注意
目前，本机身份验证 API 终结点不支持跨域资源共享 (CORS)。
先决条件
Microsoft Entra 外部租户。 如果还没有外部租户，可以创建一个。
如果尚未完成此操作，请在 Microsoft Entra 管理中心注册应用程序。 请确保授予委派的权限，并启用公共客户端和本机身份验证流。
如果尚未执行此操作，在 Microsoft Entra 管理中心中创建用户流。 创建用户流时，请记下配置的用户属性，因为这些属性是 Microsoft Entra 要求应用提交的属性。
如果是登录流，则注册客户用户，该客户用户用于测试登录 API。 或者，也可以在运行注册流之后获取该测试用户。
如果是 SSPR 流，则为外部租户中的客户用户启用自助式密码重置。 SSPR 适用于具有密码验证方法的电子邮件的客户用户。
继续标记
每次在任何流、登录、注册或 SSPR 中调用终结点时，终结点在其响应中都包含延续令牌。 延续令牌是 Microsoft Entra ID 用于在同一流中对不同终结点的调用之间保持状态的唯一标识符。 同一流中的后续请求中必须包含此令牌。
每个延续令牌在特定时间段有效，只能供同一流中的后续请求使用。
注册 API 引用
要完成任一身份验证方法的用户注册流，应用需与四个终结点（/signup/v1.0/start、/signup/v1.0/challenge、/signup/v1.0/continue和/token）交互。
注册 API 终结点
| 终结点 | 说明 |
|---|---|
/signup/v1.0/start |
此终结点启动注册流。 传递有效的应用程序 ID、新用户名和质询类型，然后返回新的延续令牌。 如果 Microsoft Entra 不支持应用程序选择的身份验证方法，终结点可以返回一个响应，以指示应用程序使用 Web 身份验证流。 |
/signup/v1.0/challenge |
你的应用使用 Microsoft Entra 支持的质询类型列表来调用此终结点。 然后，Microsoft Entra 选择要让用户进行身份验证的受支持身份验证方法之一。 |
/signup/v1.0/continue |
此终结点有助于继续流以创建用户帐户或中断流，因为缺少密码策略要求或错误的属性格式等要求。 此终结点生成延续令牌，然后将其返回到应用。 如果 Microsoft Entra 不支持应用程序选择的身份验证方法，终结点可以返回一个响应，以指示应用程序使用 Web 身份验证流。 |
/token |
应用程序调用此终结点，以最终请求安全令牌。 应用需要包含从上次成功调用/signup/v1.0/continue终结点获取的延续令牌。 |
注册质询类型
该 API 允许客户端应用在调用 Microsoft Entra 时播发其支持的身份验证方法。 应用会使用应用请求中的challenge_type参数来进行播发。 此参数包含表示不同身份验证方法的预定义值。
请在本机身份验证质询类型中详细了解质询类型。 本文介绍了应对身份验证方法使用的质询类型值。
注册流协议详细信息
序列图演示了注册过程的流。
此图表明应用在不同时间（可能在不同的屏幕上）从用户收集用户名（电子邮件）、密码（对于具有密码身份验证方法的电子邮件）和属性。 但是，你可以设计应用，以在同一屏幕中收集用户名（电子邮件）、密码以及所有必需和可选属性值，然后通过 /signup/v1.0/start 终结点提交所有这些值。 在这种情况下，应用不需要发出调用和处理可选步骤的响应。
步骤 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
| 参数 | 必需 | 说明 |
|---|---|---|
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 |
否 | 应用从客户用户处收集到的密码值。 可以通过 /signup/v1.0/continue 终结点中的 /signup/v1.0/start 或更高版本提交用户的密码。 将 {secure_password} 替换为应用从客户用户处收集到的密码值。 你有责任通过提供应用 UI 中的密码确认字段来确认用户想要使用的密码。 还必须确保用户知道根据组织策略构成强密码的内容。 详细了解 Microsoft Entra 密码策略。 此参数仅适用于具有密码身份验证方法的电子邮件。 |
attributes |
否 | 应用从客户用户处收集到的用户属性值。 该值是字符串，但采用 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 会忽略你提交的不存在的任何属性。 |
成功响应
下面是成功响应的示例：
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAA…",
}
| 参数 | 说明 |
|---|---|
continuation_token |
Microsoft Entra 返回的延续令牌。 |
如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
invalid_attributes |
未通过验证的属性列表（一组对象）。 如果应用提交用户属性，且 suberror 参数的值为 attribute_validation_failed，则可能出现此响应。 |
suberror |
错误代码字符串，可用于对错误类型进行进一步分类。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
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 参数。 以下是 invalid_grant 错误的 suberror 参数可能出现的值：
| Suberror 值 | 说明 |
|---|---|
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 参数。 以下是 invalid_client 错误的 suberror 参数可能出现的值：
| Suberror 值 | 说明 |
|---|---|
nativeauthapi_disabled |
未启用本机身份验证的应用的客户端 ID。 |
注意
如果通过 /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…
| 参数 | 必需 | 说明 |
|---|---|---|
tenant_subdomain |
是 | 你创建的外部租户的子域。 在 URL 中，将 {tenant_subdomain} 替换为目录（租户）子域。 例如，如果租户的主域为 contoso.onmicrosoft.com，则使用 contoso。 如果没有租户子域，请了解如何读取租户详细信息。 |
client_id |
是 | 在 Microsoft Entra 管理中心注册的应用程序的应用程序（客户端） ID。 |
challenge_type |
否 | 以空格分隔的应用支持的授权质询类型字符串列表，例如 oob password redirect。 列表中必须始终包含 redirect 质询类型。 对于电子邮件一次性密码，此值应为oob redirect，对于具有密码身份验证方法的电子邮件，此值应为oob password redirect。 |
continuation_token |
是 | Microsoft Entra 在前一个请求中返回的延续令牌。 |
成功响应
Microsoft Entra 将一次性密码代码发送到用户的电子邮件，然后使用 oob 值以及有关一次性密码代码的其他信息的质询类型进行响应：
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
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
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}
| 参数 | 必需 | 说明 |
|---|---|---|
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 终结点发出请求。 |
应用成功提交一次性密码代码后，注册流取决于如下表所示的方案：
| 场景 | 如何继续下一步 |
|---|---|
应用通过/signup/v1.0/start终结点成功提交用户密码（对于具有密码身份验证方法的电子邮件），并且 Microsoft Entra 管理中心未配置任何属性，或者所有必需的用户属性都通过/signup/v1.0/start终结点提交。 |
Microsoft Entra 颁发延续令牌。 如步骤 5 中所示，应用可以使用延续令牌请求获取安全令牌。 |
Microsoft Entra 通过/signup/v1.0/start成功提交用户密码（对于具有密码身份验证方法的电子邮件），但并不是所有必需的用户属性，Microsoft Entra 表明应用需要提交的属性，如需要的用户属性所示。 |
应用需要通过/signup/v1.0/continue终结点提交所需的用户属性。 响应类似于用户属性中所需的响应。 提交用户属性，如提交用户属性中所述。 |
应用不会通过/signup/v1.0/start终结点提交用户密码（对于具有密码身份验证方法的电子邮件）。 |
Microsoft Entra 的响应表明需要的凭据。 请参阅响应。 此响应可用于具有密码身份验证方法的电子邮件。 |
响应
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..."
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
continuation_token |
Microsoft Entra 返回的延续令牌。 |
suberror |
错误代码字符串，可用于对错误类型进行进一步分类。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
credential_required |
帐户创建需要身份验证，因此必须调用 /signup/v1.0/challenge 终结点来确定用户需要提供的凭据。 |
invalid_request |
请求参数验证失败，例如，延续令牌验证失败或请求未包含 client_id 参数，导致客户端 ID 为空或无效，或者外部租户管理员并未给所有租户用户都启用电子邮件 OTP 租户。 |
invalid_grant |
请求中包含的授权类型无效或不受支持，或者 OTP 值不正确。 |
expired_token |
请求中包含的延续令牌已过期。 |
如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_grant 错误的 suberror 参数可能出现的值：
| Suberror 值 | 说明 |
|---|---|
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…
| 参数 | 必需 | 说明 |
|---|---|---|
tenant_subdomain |
是 | 你创建的外部租户的子域。 在 URL 中，将 {tenant_subdomain} 替换为目录（租户）子域。 例如，如果租户的主域为 contoso.onmicrosoft.com，则使用 contoso。 如果没有租户子域，请了解如何读取租户详细信息。 |
client_id |
是 | 在 Microsoft Entra 管理中心注册的应用程序的应用程序（客户端） ID。 |
challenge_type |
否 | 以空格分隔的应用支持的授权质询类型字符串列表，例如 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..."
}
| 参数 | 说明 |
|---|---|
challenge_type |
密码在所需凭据的响应中返回。 |
continuation_token |
Microsoft Entra 返回的延续令牌。 |
如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| 参数 | 说明 |
|---|---|
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}
| 参数 | 必需 | 说明 |
|---|---|---|
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 终结点提交，则应用获取延续令牌而不提交任何属性。 如步骤 5 中所示，应用可以使用延续令牌请求获取安全令牌。 否则，Microsoft Entra 的响应表明应用需要提交所需的属性。 这些属性无论是内置还是自定义，都是由租户管理员在 Microsoft Entra 管理中心配置的。
所需的用户属性
此响应请求应用提交名称、*age 和手机属性的值。
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]*$"
}
}
],
}
注意
自定义属性（也称为目录扩展）使用约定 extension_{appId-without-hyphens}_{attribute-name} 进行命名，其中 {appId-without-hyphens} 是扩展应用客户端 ID 的剥离版本。 例如，如果扩展应用的客户端 ID 为 2588a-bcdwh-tfeehj-jeeqw-ertc，且属性名称为爱好，则自定义属性被命名为 extension_2588abcdwhtfeehjjeeqwertc_hobbies。 详细了解自定义属性和扩展应用。
| 参数 | 说明 |
|---|---|
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 参数可能的值）：
| 错误值 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
suberror |
错误代码字符串，可用于对错误类型进行进一步分类。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
invalid_request |
请求参数验证失败，例如，当 challenge_type 参数包含无效的质询类型。 |
invalid_grant |
提交的授权无效，例如提交的密码太短。 使用 suberror 参数了解错误的具体原因。 |
expired_token |
延续令牌已过期。 |
attributes_required |
一个或多个用户属性是必需的。 |
如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 suberror 参数可能出现的值：
| Suberror 值 | 说明 |
|---|---|
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}", "postaCode": "{postal_code}"}
&continuation_token=AQABAAEAAAAtn...
| 参数 | 必需 | 说明 |
|---|---|---|
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 会颁发延续令牌，应用可以使用该令牌请求安全令牌。
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "AQABAAEAAAYn..."
}
| 参数 | 说明 |
|---|---|
continuation_token |
Microsoft Entra 返回的延续令牌。 |
如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
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 参数的值为 attribute_validation_failed 时，响应中包含此参数。 |
suberror |
错误代码字符串，可用于对错误类型进行进一步分类。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
invalid_request |
请求参数验证失败，例如，延续令牌验证失败或请求未包含 client_id 参数，导致客户端 ID 为空或无效。 |
invalid_grant |
提供的授权类型无效或不受支持或验证失败，例如属性验证失败。 使用 suberror 参数了解错误的具体原因。 |
expired_token |
请求中包含的延续令牌已过期。 |
attributes_required |
一个或多个用户属性是必需的。 |
如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_grant 错误的 suberror 参数可能出现的值：
| Suberror 值 | 说明 |
|---|---|
attribute_validation_failed |
用户属性验证失败。 invalid_attributes 参数包含未通过验证的属性列表（一组对象）。 |
步骤 5：请求安全令牌
应用向 /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=ABAAEAAAAtyo...
&client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&username=contoso-consumer@contoso.com
&scope={scopes}
&grant_type=continuation_token
| 参数 | 必需 | 说明 |
|---|---|---|
tenant_subdomain |
是 | 你创建的外部租户的子域。 在 URL 中，将 {tenant_subdomain} 替换为目录（租户）子域。 例如，如果租户的主域为 contoso.onmicrosoft.com，则使用 contoso。 如果没有租户子域，请了解如何读取租户详细信息。 |
client_id |
是 | 在 Microsoft Entra 管理中心注册的应用程序的应用程序（客户端） ID。 |
grant_type |
是 | 参数值必须为延续令牌。 |
continuation_token |
是 | Microsoft Entra 在前一个步骤中返回的延续令牌。 |
scope |
是 | 以空格分隔的访问令牌有效的范围列表。 将 {scopes} 替换为 Microsoft Entra 返回为有效的访问令牌的有效范围。 |
username |
是 | 客户用户注册时要使用的电子邮件，例如 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..."
}
| 参数 | 说明 |
|---|---|
access_token |
应用从 /token 终结点请求的访问令牌。 应用可以使用此访问令牌请求访问 Web API 等安全的资源。 |
token_type |
指示令牌类型值。 Microsoft Entra 支持的唯一类型是 Bearer。 |
expires_in |
访问令牌保持有效的时间长度（以秒为单位）。 |
scopes |
以空格分隔的访问令牌有效的范围列表。 |
refresh_token |
OAuth 2.0 刷新令牌。 应用可以使用此令牌，在当前访问令牌过期之后获取其他访问令牌。 刷新令牌的生存期较长。 它们可以长期保留对资源的访问权限。 有关刷新访问令牌的详细信息，请参阅刷新访问令牌一文。 注意：仅当请求 offline_access 范围时才颁发。 |
id_token |
用于识别客户用户的 JSON Web 令牌。 应用可以解码此令牌，以读取已登录用户的相关信息。 应用可以缓存并显示值，机密客户端可以使用此令牌进行授权。 有关 ID令牌的详细信息，请参阅 ID 令牌。 注意：仅当请求 openid 范围时才颁发。 |
错误响应
示例：
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "invalid_request",
"error_description": "AADSTS901007: The client doesn't have consent for the requested scopes.\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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
invalid_request |
请求参数验证失败，例如，客户端/应用没有获得请求的范围的同意。 |
invalid_grant |
请求中包含的延续令牌无效。 |
unauthorized_client |
请求中包含的客户端 ID 无效或不存在。 |
unsupported_grant_type |
请求中包含的授权类型不受支持或不正确。 |
将用户属性提交到终结点
在 Microsoft Entra 管理中心中，可以根据需要或可以选择配置用户属性。 此配置会确定在调用终结点时 MiMicrosoft EntrEntra 的响应方式。 可选属性对于完成注册流不是必需的。 因此，当所有属性都是可选内容时，必须先提交它们，然后才能验证用户名。 否则，注册无需可选属性即可完成。
下表汇总了何时可以将用户属性提交到 Microsoft Entra 终结点。
| 终结点 | 必需属性 | 可选属性 | 必需属性和可选属性 |
|---|---|---|---|
/signup/v1.0/start 终结点 |
是 | 是 | 是 |
进行用户名验证前的 /signup/v1.0/continue 终结点 |
是 | 是 | 是 |
进行用户名验证后的 /signup/v1.0/continue 终结点 |
是 | No | 是 |
用户属性值的格式
通过在 Microsoft Entra 管理中心配置用户流设置来指定要从用户收集的信息。 查看在注册过程中收集自定义用户属性一文，了解如何收集内置和自定义两种属性的值。
还可以为你配置的属性指定用户输入类型。 下表总结了受支持的用户输入类型，以及如何将 UI 控件收集到的值提交给 Microsoft Entra。
| 用户输入类型 | 提交的值的格式 |
|---|---|
| TextBox | 职务、软件工程师等单个值。 |
| 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 管理中心中的“显示名称”在 API 中引用为 displayName。
请参阅用户配置文件属性一文，了解如何在本地身份验证 API 中同时引用内置和自定义用户属性。
登录 API 参考
用户需要使用其注册的身份验证方法登录。 例如，使用具有密码身份验证方法的电子邮件注册的用户必须使用电子邮件和密码登录。
若要请求安全令牌，应用需要与 /initiate、/challenge 和 /token 这三个终结点交互。
登录 API 终结点
| 终结点 | 说明 |
|---|---|
/initiate |
此终结点启动登录流。 如果你的应用使用已存在的用户帐户的用户名调用它，它将返回包含延续令牌的成功响应。 如果你的应用请求使用 Microsoft Entra 不支持的身份验证方法，此终结点响应可以向应用指示，它需要使用基于浏览器的身份验证流。 |
/challenge |
你的应用使用标识服务支持的质询类型列表来调用此终结点。 标识服务生成，然后将一次性密码代码发送到所选质询通道，例如电子邮件。 如果应用反复调用此终结点，则每次调用时都会发送一个新的 OTP。 |
/token |
此终结点验证它从应用收到的一次性密码代码，然后将安全令牌颁发给应用。 |
登录质询类型
该 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
| 参数 | 必需 | 说明 |
|---|---|---|
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。 |
成功响应
下面是成功响应的示例：
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| 参数 | 说明 |
|---|---|
continuation_token |
Microsoft Entra 返回的延续令牌。 |
如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
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 参数。 以下是 invalid_client 错误的 suberror 参数可能出现的值：
| Suberror 值 | 说明 |
|---|---|
nativeauthapi_disabled |
未启用本机身份验证的应用的客户端 ID。 |
步骤 2：选择身份验证方法
应用使用上一步中获得的延续令牌请求 Microsoft Entra 选择其中一个受支持的质询类型供用户进行身份验证，流才能继续进行。 应用向 /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...
| 参数 | 必需 | 说明 |
|---|---|---|
tenant_subdomain |
是 | 你创建的外部租户的子域。 在 URL 中，将 {tenant_subdomain} 替换为目录（租户）子域。 例如，如果租户的主域为 contoso.onmicrosoft.com，则使用 contoso。 如果没有租户子域，请了解如何读取租户详细信息。 |
client_id |
是 | 在 Microsoft Entra 管理中心注册的应用程序的应用程序（客户端） ID。 |
continuation_token |
是 | Microsoft Entra 在前一个请求中返回的延续令牌。 |
challenge_type |
否 | 以空格分隔的应用支持的授权质询类型字符串列表，例如 oob password redirect。 列表中必须始终包含 redirect 质询类型。 对于电子邮件一次性密码，此值应为oob redirect，对于具有密码的电子邮件，此值应为password redirect。 |
成功响应
- 电子邮件一次性密码
- 带密码的电子邮件
如果租户管理员在 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
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
invalid_request |
请求参数验证失败，例如，当 challenge_type 参数包含无效的质询类型。 |
invalid_grant |
请求中包含的延续令牌无效。 |
expired_token |
请求中包含的延续令牌已过期。 |
unsupported_challenge_type |
challenge_type 参数值不包含 redirect 质询类型。 |
步骤 3：请求安全令牌
应用向 /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
| 参数 | 必需 | 说明 |
|---|---|---|
tenant_subdomain |
是 | 你创建的外部租户的子域。 在 URL 中，将 {tenant_subdomain} 替换为目录（租户）子域。 例如，如果租户的主域为 contoso.onmicrosoft.com，则使用 contoso。 如果没有租户子域，请了解如何读取租户详细信息。 |
client_id |
是 | 在 Microsoft Entra 管理中心注册的应用程序的应用程序（客户端） ID。 |
continuation_token |
是 | Microsoft Entra 在前一个请求中返回的延续令牌。 |
grant_type |
是 | 对于具有密码身份验证方法的电子邮件，该值必须为密码，对于电子邮件一次性密码身份验证方法，该值必须为oob。 |
scope |
是 | 范围的空格分隔列表。 所有范围必须来自同一来源，以及 OpenID Connect (OIDC) 范围，例如配置文件、*openid 和电子邮件。 应用需要包含 openid 范围，Microsoft Entra 才能颁发 ID 令牌。 应用需要包含 offline_access 范围，Microsoft Entra 才能颁发刷新令牌。 详细了解 Microsoft 标识平台中的权限和同意。 |
password |
是 （对于具有密码的电子邮件） |
应用从客户用户处收集到的密码值。 将 {secure_password} 替换为应用从客户用户处收集到的密码值。 |
oob |
是 （对于电子邮件一次性密码） |
客户用户在其电子邮件中收到的一次性密码。 将 {otp_code} 替换为客户用户在其电子邮件中收到的一次性密码。 要重新发送一次性密码，应用需要再次向 /challenge 终结点发出请求。 |
成功的响应
下面是成功响应的示例：
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..."
}
| 参数 | 说明 |
|---|---|
token_type |
指示令牌类型值。 Microsoft Entra 支持的唯一类型是 Bearer。 |
scopes |
以空格分隔的访问令牌有效的范围列表。 |
expires_in |
访问令牌保持有效的时间长度（以秒为单位）。 |
access_token |
应用从 /token 终结点请求的访问令牌。 应用可以使用此访问令牌请求访问 Web API 等安全的资源。 |
refresh_token |
OAuth 2.0 刷新令牌。 应用可以使用此令牌，在当前访问令牌过期之后获取其他访问令牌。 刷新令牌的生存期较长。 它们可以长期保留对资源的访问权限。 有关刷新访问令牌的详细信息，请参阅刷新访问令牌一文。 注意：只有当请求offline_access范围时才发出。 |
id_token |
用于识别客户用户的 JSON Web 令牌。 应用可以解码此令牌，以请求已登录用户的相关信息。 应用可以缓存并显示值，机密客户端可以使用此令牌进行授权。 有关 ID令牌的详细信息，请参阅 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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
invalid_request |
请求参数验证失败。 使用错误描述中的消息了解发生了什么。 |
invalid_grant |
请求中包含的延续令牌无效或请求中包含的客户用户登录凭据无效，或者请求中包含的授权类型未知。 |
invalid_client |
请求中包含的客户端 ID 不适用于公共客户端。 |
expired_token |
请求中包含的延续令牌已过期。 |
invalid_scope |
请求中包含的一个或多个作用域无效。 |
如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_grant 错误的 suberror 参数可能出现的值：
| Suberror 值 | 说明 |
|---|---|
invalid_oob_value |
一次性密码的值无效。 此子错误仅应用电子邮件一次性密码 |
自助式密码重置 (SSPR)
如果使用电子邮件和密码作为应用中的身份验证方法，请使用自助式密码重置 (SSPR) API，使客户用户能够重置其密码。 请将此 API 用于忘记密码或更改密码场景。
自助式密码重置 API 终结点
若要使用此 API，应用与下表中显示的终结点进行交互：
| 终结点 | 说明 |
|---|---|
/start |
当客户用户选择应用中的“忘记密码”或“更改密码”链接或按钮时，应用将调用此终结点。 此终结点验证用户的用户名（电子邮件），然后返回延续令牌，以便在密码重置流中使用。 如果你的应用请求使用 Microsoft Entra 不支持的身份验证方法，此终结点响应可以向应用指示，它需要使用基于浏览器的身份验证流。 |
/challenge |
接受客户端支持的质询类型列表和延续令牌。 向首选恢复凭据之一颁发质询。 例如，oob 质询向与客户用户帐户关联的电子邮件发出带外一次性密码代码。 如果你的应用请求使用 Microsoft Entra 不支持的身份验证方法，此终结点响应可以向应用指示，它需要使用基于浏览器的身份验证流。 |
/continue |
验证 /challenge 终结点颁发的质询，然后为 /submit 终结点返回延续令牌，或向用户发出另一个质询。 |
/submit |
接受用户输入的新密码以及延续令牌，以完成密码重置流。 此终结点颁发另一个延续令牌。 |
/poll_completion |
最后，应用可以使用 /submit 终结点颁发的延续令牌来检查密码重置请求的状态。 |
自助式密码重置质询类型
该 API 允许应用在调用 Microsoft Entra 时播发其支持的身份验证方法。 为此，应用会使用其请求中的 challenge_type 参数来进行播发。 此参数包含表示不同身份验证方法的预定义值。
对于 SSPR 流，质询类型值为 oob 和 redirect。
请在本机身份验证质询类型中详细了解质询类型。
自助式密码重置流协议流
序列图演示了密码重置过程的流。
此图表明应用在不同时间（可能在不同的屏幕上）从用户收集用户名（电子邮件）和密码。 但是，你可以设计应用，以在同一屏幕上收集用户名（电子邮件）和新密码。 在本例中，应用保存密码，然后通过 /submit 终结点提交密码。
步骤 1：请求开始自助式密码重置流
密码重置流从向 /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
| 参数 | 必需 | 说明 |
|---|---|---|
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。 |
成功响应
示例：
HTTP/1.1 200 OK
Content-Type: application/json
{
"continuation_token": "uY29tL2F1dGhlbnRpY..."
}
| 参数 | 说明 |
|---|---|
continuation_token |
Microsoft Entra 返回的延续令牌。 |
如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：
HTTP/1.1 200 OK
Content-Type: application/json
{
"challenge_type": "redirect"
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
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 参数。 以下是 invalid_client 错误的 suberror 参数可能出现的值：
| Suberror 值 | 说明 |
|---|---|
nativeauthapi_disabled |
未启用本机身份验证的应用的客户端 ID。 |
步骤 2：选择身份验证方法
应用使用上一步中获得的延续令牌请求 Microsoft Entra 选择其中一个受支持的质询类型供用户进行身份验证，流才能继续进行。 应用向 /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=client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&challenge_type=oob redirect
&continuation_token=uY29tL2F1dGhlbnRpY...
| 参数 | 必需 | 说明 |
|---|---|---|
tenant_subdomain |
是 | 你创建的外部租户的子域。 在 URL 中，将 {tenant_subdomain} 替换为目录（租户）子域。 例如，如果租户的主域为 contoso.onmicrosoft.com，则使用 contoso。 如果没有租户子域，请了解如何读取租户详细信息。 |
client_id |
是 | 在 Microsoft Entra 管理中心注册的应用程序的应用程序（客户端） ID。 |
continuation_token |
是 | Microsoft Entra 在前一个请求中返回的延续令牌。 |
challenge_type |
否 | 以空格分隔的应用支持的授权质询类型字符串列表，例如 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
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
invalid_request |
请求参数验证失败，例如，当 challenge_type 参数包含无效的质询类型或延续令牌验证失败。 |
expired_token |
延续令牌已过期。 |
unsupported_challenge_type |
challenge_type 参数值不包含 redirect 质询类型。 |
步骤 3：提交一次性密码
然后应用向 /continue 终结点发出 POST 请求。 在请求中，应用需要包括在上一步中选择的用户凭据以及从 /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}
| 参数 | 必需 | 说明 |
|---|---|---|
tenant_subdomain |
是 | 你创建的外部租户的子域。 在 URL 中，将 {tenant_subdomain} 替换为目录（租户）子域。 例如，如果租户的主域为 contoso.onmicrosoft.com，则使用 contoso。 如果没有租户子域，请了解如何读取租户详细信息。 |
continuation_token |
是 | Microsoft Entra 在前一个请求中返回的延续令牌。 |
client_id |
是 | 在 Microsoft Entra 管理中心注册的应用程序的应用程序（客户端） ID。 |
grant_type |
是 | 唯一的有效值为 oob。 |
oob |
是 | 客户用户在其电子邮件中收到的一次性密码。 将 {otp_code} 替换为客户用户在其电子邮件中收到的一次性密码。 要重新发送一次性密码，应用需要再次向 /challenge 终结点发出请求。 |
成功响应
示例：
HTTP/1.1 200 OK
Content-Type: application/json
{
"expires_in": 600,
"continuation_token": "czZCaGRSa3F0MzpnW...",
}
| 参数 | 说明 |
|---|---|
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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
suberror |
错误代码字符串，可用于对错误类型进行进一步分类。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
invalid_request |
请求参数验证失败，例如，延续令牌验证失败或请求未包含 client_id 参数，导致客户端 ID 为空或无效，或者外部租户管理员并未给所有租户用户都启用 SSPR 和电子邮件 OTP 租户。 使用 error_description 参数了解错误的具体原因。 |
invalid_grant |
授权类型未知或与预期的授予类型值不匹配。 使用 suberror 参数了解错误的具体原因。 |
expired_token |
延续令牌已过期。 |
如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_grant 错误的 suberror 参数可能出现的值：
| Suberror 值 | 说明 |
|---|---|
invalid_oob_value |
用户提供的一次性密码无效。 |
步骤 4：提交新密码
应用从用户那里收集新密码，然后使用 /continue 终结点颁发的延续令牌向 /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}
| 参数 | 必需 | 说明 |
|---|---|---|
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
}
| 参数 | 说明 |
|---|---|
continuation_token |
Microsoft Entra 返回的延续令牌。 |
poll_interval |
应用在轮询请求之间通过 /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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
suberror |
错误代码字符串，可用于对错误类型进行进一步分类。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
invalid_request |
请求参数验证失败，例如延续令牌验证失败。 |
expired_token |
延续令牌已过期。 |
invalid_grant |
提交的授权无效，例如提交的密码太短。 使用 suberror 参数了解错误的具体原因。 |
如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 suberror 参数可能出现的值：
| Suberror 值 | 说明 |
|---|---|
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：轮询密码重置状态
最后，由于使用新密码更新用户配置会产生一些延迟，因此应用可以使用 /poll_completion 终结点来轮询 Microsoft Entra，以获取密码重置状态。 应用应在轮询请求之间等待的最短时间（以秒为单位）从 poll_interval 参数中的 /submit 终结点返回。
下面是示例（为方便查看，我们用多行展示该示例）：
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...
| 参数 | 必需 | 说明 |
|---|---|---|
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..."
}
| 参数 | 说明 |
|---|---|
status |
重置密码请求的状态。 如果 Microsoft Entra 返回失败的状态，则应用可以通过向 /submit 终结点发出另一个请求，并包括新的延续令牌来重新提交新密码。 |
continuation_token |
Microsoft Entra 返回的延续令牌。 如果状态为成功，则应用可以使用 Microsoft Entra 返回的延续令牌通过 /token 终结点请求安全令牌，如注册流步骤 5 中所述。 这意味着，用户成功重置其密码后，无需启动新的登录流，即可直接登录到应用。 |
下面是 Microsoft Entra 可能返回的状态（status 参数的可能值）：
| 错误值 | 说明 |
|---|---|
succeeded |
密码重置成功完成。 |
failed |
密码重置失败。 应用可以通过向 /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"
}
| 参数 | 说明 |
|---|---|
error |
一个错误代码字符串，可用于对错误类型进行分类并对错误做出反应。 |
error_description |
可帮助用户识别身份验证错误原因的特定错误消息。 |
error_codes |
特定于 Microsoft Entra 的错误代码列表，可帮助你诊断错误。 |
timestamp |
发生错误的时间。 |
trace_id |
帮助诊断错误的请求唯一标识符。 |
correlation_id |
可帮助跨组件诊断的请求唯一标识符。 |
以下是可能会遇到的一些错误（error 参数可能的值）：
| 错误值 | 说明 |
|---|---|
invalid_request |
请求参数验证失败，例如延续令牌验证失败。 |
expired_token |
延续令牌已过期。 |