Authany 如何与您的应用集成¶

提示

为简单起见，建议使用 Authany SDK（JS、iOS、Android）将 Authany 接入您的应用。

这些 SDK 实际上只是一层简单的封装 —— 在背后，使用 Authany 进行身份验证并维持会话有两种推荐方式。

本概念文档旨在说明背后的工作原理。

基于 Token¶

移动端或单页 Web 应用¶

JS SDK 和移动端 SDK 会按照 OIDC 2.0 标准，在 [your app name].authgear.com/oauth2/authorize?... 与 Authany 完成身份验证。

如果身份验证成功，/oauth2/authorize 会向客户端应用返回 access token（访问令牌）和 refresh token（刷新令牌）。

SDK 会自动使用 refresh token 为您续期 access token，您无需关心这个过程。

您的应用应在请求后端时，将访问令牌放在 Authorization 请求头中调用后端，您可以通过 [your app name].authgear.com/_resolver/resolve 验证访问令牌（详见此处）；另外，访问令牌本身是经过签名的 JWT，您也可以在后端本地验证。

最后，应用可以调用 [your app name].authgear.com/oauth2/revoke 来登出。

因此，使用这种集成方式时，您需要理解以下几点影响：

某些功能，例如在管理台中禁用或登出某个会话，只有在访问令牌下一次过期时才会生效，因此您可能需要把「Access Token Lifetime」（访问令牌有效期）设置得更短一些。
您可能希望自行验证 JWT 访问令牌，以避免调用 /_resolver/resolve 端点带来的延迟。

同一根域名下的 Web 应用（服务端渲染）¶

如果您在 yourdomain.com 下托管一个服务端渲染的 Web 应用，例如 Ruby on Rails、PHP、ASP .NET 等，建议您为 Authany 设置一个自定义域名，例如 identity.yourdomain.com。

在这种配置下，如果您在 yourdomain.com 下有多个应用，所有应用会自动共享同一份会话 Cookie。

登录时，您需要将用户重定向到 identity.yourdomain.com/oauth2/authorize? 并带上 redirect_uri 参数。身份验证成功后，Authany 会将用户重定向回该 URI，并设置一个带有会话访问令牌的 Cookie。

您的后端可以通过 /_resolver/resolve 验证这个会话访问令牌。

不同域名下的 Web 应用（服务端渲染）¶

如果您的服务端渲染 Web 应用托管在 otherapp.com 下，但您希望在 identity.yourdomain.com 下进行用户身份验证，而不是为 identity.otherapp.com 再单独设置一个自定义域名，以获得更好的单点登录体验，从概念上讲，您需要执行以下步骤：

通过重定向到 identity.yourdomain.com/oauth2/authorize?... 对用户进行身份验证。
验证成功后，从 identity.yourdomain.com/oauth2/token 获取 access token 和 refresh token。
在 otherapp.com 上创建您自己的 Cookie 会话，Cookie 内容可以使用访问令牌。
一旦访问令牌过期，使用刷新令牌获取新的访问令牌。
如果用户请求登出，或使用刷新令牌获取新访问令牌失败（意味着会话已被撤销），则清除您的 Cookie 会话。

关于如何完成这项配置，请参阅将 Authany 作为 OIDC 提供方使用。

提示

TODO：针对这种情况编写一份进阶指南。