身份验证流程 API¶
通过身份验证流程 API，构建您自己的登录、注册等自定义 UI。
默认情况下，创建 Authany 项目后会使用 Authany 提供的常规 AuthUI。虽然 AuthUI 提供了许多自定义选项，例如更改主题和颜色，或在身份验证页面添加您的品牌 Logo，但您可能还有更多需求。借助身份验证流程 API，您可以使用自己偏好的编程语言和工具，从零开始构建自己的身份验证 UI。
什么是身份验证流程 API？¶
身份验证流程 API 是一个 REST HTTP API，您可以用它来创建并运行身份验证流程。您可以使用此 API 为登录、注册、账号找回、双重验证等页面构建自己的自定义 UI。
要单独使用该 API，您需要向下面所示的某个有效端点发起 HTTP 请求：
端点： {your-authgear-project-domain}/api/v1/authentication_flows
请求方法： POST
请求头：
所有对该 API 的请求都应包含上述请求头。
请求体：
以下是针对上述请求，从身份验证流程 API 得到的响应示例：
{
"result": {
"state_token": "authflowstate_VGHZ8SBCKGZK2KW84TCAKWGM8QZH0B69",
"type": "login",
"name": "default",
"action": {
"type": "identify",
"data": {
"options": [
{
"identification": "phone"
},
{
"identification": "email"
},
{
"identification": "oauth",
"oauth_provider_type": "google",
"oauth_provider_alias": "google"
}
]
}
}
}
}
上面的响应表示您已通过该 API 成功开始了一个新的登录流程。
说明
如果浏览器中已经有一个活跃的 Authany 会话，并且您的流程配置启用了该功能，options 数组中还可能包含一个 select_account 条目。这让用户无需重新输入凭据即可以现有账号继续。参见使用自定义 UI 实现单点登录延续。
要继续并完成身份验证流程，您可以在下一个 HTTP 请求中，将上述响应中的 state_token 的值发送到 api/v1/authentication_flows/states/input 端点，如下例所示：
端点： {your-authgear-project-domain}/api/v1/authentication_flows/states/input
请求方法： POST
为帮助您理解身份验证流程 API 的 HTTP(S) 请求结构，下面是一个在 Postman 中实际请求的示例：
请求体：
{
"state_token": "authflowstate_VGHZ8SBCKGZK2KW84TCAKWGM8QZH0B69",
"input": {
"identification": "email",
"login_id": "user@example.com"
}
}
在这第二个请求中（即身份验证流程的第二步），我们在请求体中使用上一个请求响应里的 state_token 来继续身份验证流程。请求体包含 input 字段，用于传递用户将提供的 identification 类型（例如 email），以及 login_id，即用户身份标识的实际值。
上述请求的响应应如下所示：
{
"result": {
"state_token": "authflowstate_ABCJVB0IJKLQ2S1K2G34RX56R1C1E789",
"type": "login",
"name": "default",
"action": {
"type": "authenticate",
"data": {
"type": "authentication_data",
"options": [
{
"authentication": "primary_password"
}
],
"device_token_enabled": false
}
}
}
}
根据您具体身份验证流程所需的步骤数，您可以发送更多类似这第二个请求的请求。例如，要完成登录身份验证流程，可以像这样再发送一个带有验证方式（密码）的请求：
{
"state_token": "authflowstate_ABCJVB0IJKLQ2S1K2G34RX56R1C1E789",
"input": {
"authentication": "primary_password",
"password": "sup3r$tr0ngpa$$"
}
}
要使用身份验证流程 API 来构建您的自定义 UI，您需要在 Authany 管理台中配置一个自定义 UI URI。该 URI 应指向您的自定义身份验证页面。
有关身份验证流程 API 端点、输入、响应等更多详情，请访问 API 参考页面。
身份验证流程 API 的工作原理¶
下面的流程图展示了一个简单的身份验证流程 API 实现中的各个步骤：
展示身份验证流程 API 工作原理的流程图
第 1 步：发起授权请求¶
当您使用身份验证流程 API 来驱动自定义 UI 时，应用的身份验证流程会以应用向 Authany 授权服务器发送授权请求开始，如上图第 1 步所示。
第 2 步：重定向到自定义 UI¶
如果您已启用身份验证流程 API，并为您的 Authany 应用设置了自定义 UI URI，授权服务器会将用户重定向到自定义 UI，如上图第 2 步所示。
重定向会带上 client_id、redirect_uri、x_ref 等查询参数，您的自定义 UI 应通过 url_query 将这些参数转发回该 API。如果授权请求中带有 login_hint 或 id_token_hint，这些参数也会随重定向一并转发。您的自定义 UI 可以读取它们，用于预填身份标识字段，或决定是否提供单点登录延续。
第 3 步：向身份验证流程 API 端点发起 HTTP 请求¶
在您的自定义 UI 中，实现与身份验证流程 API 交互的代码（通过 HTTP 请求），如上图第 3 步所示。
第 4 步：完成身份验证流程¶
在包含多个步骤的身份验证流程中，自定义 UI 与 Authany 的身份验证服务器可能会多次执行上图中的第 3 步和第 4 步。在这种情况下，只有身份验证流程结束时的最终响应才会包含 finish_redirect_url。
您必须将用户重定向到 finish_redirect_url，以完成身份验证流程。
要进一步了解如何使用身份验证流程 API 来驱动您的自定义 UI，请查看以下针对您偏好的编程语言和框架的教程。