本机身份验证 API 参考

应用于： 员工租户 外部租户（了解详细信息）

Microsoft Entra 的本机身份验证使你可以在客户端应用程序中托管应用的用户界面，而不是将身份验证委托给浏览器，从而带来本机集成的身份验证体验。 作为开发人员，你可以完全控制登录界面的外观。

此 API 参考文章介绍了只当你手动发送原始 HTTP 请求以执行流时必需的详细信息。 但是，我们不建议采用这种方法。 因此，如果条件允许，请使用 Microsoft 构建和支持的身份验证 SDK。 要详细了解如何使用 SDK，请参阅教程：准备 Android 移动应用以进行本机身份验证和教程：准备 iOS/macOS 移动应用以进行本机身份验证。

成功调用 API 端点时，会同时收到用于用户身份验证的 ID 令牌和用于调用受保护的 API 的访问令牌。 来自 API 的所有响应均采用 JSON 格式。

Microsoft Entra 的本机身份验证 API 支持两种身份验证方法的注册和登录：

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

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

先决条件

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

2. 如果尚未完成此操作，请在 Microsoft Entra 管理中心注册应用程序。 请确保授予委派的权限，并启用公共客户端和本机身份验证流。

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

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

5. 如果是登录流，则注册客户用户，该客户用户用于测试登录 API。 或者，也可以在运行注册流之后获取该测试用户。

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

延续令牌

每次在任何流、登录、注册或 SSPR 中调用端点时，端点在其响应中都包含延续令牌。 延续令牌是 Microsoft Entra ID 用于在同一流中对不同端点的调用之间保持状态的唯一标识符。 同一流中的后续请求中必须包含此令牌。

每个延续令牌在特定时间段有效，只能供同一流中的后续请求使用。

注册 API 引用

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

注册 API 端点

注册质询类型

该 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 

成功响应

下面是成功响应的示例：

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

{
    "continuation_token": "AQABAAEAAA…",
} 

如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：

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

{     
   "challenge_type": "redirect" 
} 

虽然此响应视为成功响应，但应用需要切换到基于 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 参数可能的值）：

如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_grant 错误的 suberror 参数可能出现的值：

如果错误参数具有 invalid_client 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_client 错误的 suberror 参数可能出现的值：

步骤 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…

成功响应

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
} 

如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：

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

{
   "challenge_type": "redirect"
}

虽然此响应视为成功响应，但应用需要切换到基于 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 参数可能的值）：

步骤 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}

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

响应

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 参数可能的值）：

如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_grant 错误的 suberror 参数可能出现的值：

如果要从用户收集密码凭证，应用需要调用 /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…

成功响应

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

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

{
    "challenge_type": "password",
    "continuation_token": " AQABAAEAAAAty..."
}

如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：

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

{     
    "challenge_type": "redirect" 
} 

虽然此响应视为成功响应，但应用需要切换到基于 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}

成功响应

如果请求成功，但 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]*$"
            }
        }
    ],
}

以下是可能会遇到的一些错误（error 参数可能的值）：

如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：

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

{     
   "challenge_type": "redirect" 
} 

虽然此响应视为成功响应，但应用需要切换到基于 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 参数可能的值）：

如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 suberror 参数可能出现的值：

提交用户属性

应用需要调用 /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...

成功响应

如果请求成功，Microsoft Entra 会颁发延续令牌，应用可以使用该令牌请求安全令牌。

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

{  
    "continuation_token": "AQABAAEAAAYn..."
} 

如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：

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

{     
   "challenge_type": "redirect" 
} 

虽然此响应视为成功响应，但应用需要切换到基于 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 参数可能的值）：

如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_grant 错误的 suberror 参数可能出现的值：

步骤 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 

成功的响应

下面是成功响应的示例：

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..."
}

错误响应

示例：

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 参数可能的值）：

将用户属性提交到端点

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

下表汇总了何时可以将用户属性提交到 Microsoft Entra 端点。

用户属性值的格式

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

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

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

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 端点

登录质询类型

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

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

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

注册流协议详细信息

序列图演示了登录过程的流。

在后续部分中，我们将序列图流汇总为三个基本步骤。

步骤 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 

成功响应

下面是成功响应的示例：

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：

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

{     
   "challenge_type": "redirect" 
} 

虽然此响应视为成功响应，但应用需要切换到基于 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 参数可能的值）：

如果错误参数具有 invalid_client 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_client 错误的 suberror 参数可能出现的值：

步骤 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... 

成功响应

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
} 

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

{   
   "continuation_token": "uY29tL2F1dGhlbnRpY",   
   "challenge_type": "password" 
} 

如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：

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

{     
   "challenge_type": "redirect" 
} 

虽然此响应视为成功响应，但应用需要切换到基于 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 参数可能的值）：

步骤 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 

成功的响应

下面是成功响应的示例：

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..."
}

错误响应

示例：

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 参数可能的值）：

如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_grant 错误的 suberror 参数可能出现的值：

自助式密码重置 (SSPR)

如果使用电子邮件和密码作为应用中的身份验证方法，请使用自助式密码重置 (SSPR) API，使客户用户能够重置其密码。 请将此 API 用于忘记密码或更改密码场景。

自助式密码重置 API 端点

如果要使用此 API，应用与下表中显示的端点进行交互：

自助式密码重置质询类型

该 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 

成功响应

示例：

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY..."
}

如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：

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

{     
   "challenge_type": "redirect" 
} 

虽然此响应视为成功响应，但应用需要切换到基于 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 参数可能的值）：

如果错误参数具有 invalid_client 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_client 错误的 suberror 参数可能出现的值：

步骤 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... 

成功响应

示例：

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
} 

如果应用无法支持 Microsoft Entra 所需的身份验证方法，则需要回退到基于 Web 的身份验证流。 在此场景下，Microsoft Entra 会通过在其响应中返回 redirect 质询类型来通知应用：

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

{     
   "challenge_type": "redirect" 
} 

虽然此响应视为成功响应，但应用需要切换到基于 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 参数可能的值）：

步骤 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}

成功响应

示例：

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

{ 
    "expires_in": 600,
    "continuation_token": "czZCaGRSa3F0MzpnW...",
} 

错误响应

示例：

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 参数可能的值）：

如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 invalid_grant 错误的 suberror 参数可能出现的值：

步骤 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}

成功响应

示例：

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

{
    "continuation_token": "uY29tL2F1dGhlbnRpY...",
    "poll_interval": 2
}

错误响应

示例：

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 参数可能的值）：

如果错误参数具有 invalid_grant 的值，Microsoft Entra 会在其响应中包含 suberror 参数。 以下是 suberror 参数可能出现的值：

步骤 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... 

成功响应

示例：

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

{
    "status": "succeeded",
    "continuation_token":"czZCaGRSa3F0..."
} 

下面是 Microsoft Entra 可能返回的状态（status 参数的可能值）：

错误响应

示例：

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 参数可能的值）：

相关内容

• 配置自定义声明提供程序。