Keycloak中的离线令牌与用户注销

在Keycloak中，离线令牌（Offline Token）是一个非常有用的功能，它允许应用程序在用户注销后仍然能够获取新的访问令牌。然而，实践中如何正确使用这些令牌，理解其与用户注销的关系是至关重要的。下面我们将探讨Keycloak的离线令牌机制，以及在注销过程中的一些常见误区。

理解离线令牌

离线令牌是Keycloak提供的一种特殊类型的令牌，它可以在用户不在线时继续使用。它的设计初衷是让应用程序即使在用户注销后，仍能进行一些后台操作，如定时任务、数据同步等。

离线令牌的获取

要获取离线令牌，首先需要在获取授权码时指定scope=openid offline_access。例如：

POST /openid-connect/token HTTP/1.1 Host: your-keycloak-server.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=your_authorization_code&client_id=your_client_id&client_secret=your_client_secret&redirect_uri=your_redirect_uri&scope=openid offline_access

获取的响应中会包含refresh_token，这就是所谓的离线令牌。

注销与离线令牌

注销的定义

注销在Keycloak中可以有两种理解：

1. 本地客户端注销：这意味着用户在客户端上注销了，但并不影响Keycloak服务器上的用户会话。此时，离线令牌仍然有效，应用程序可以继续使用这些令牌来获取新的访问令牌。

2. Keycloak服务器注销：这种注销会直接影响到Keycloak服务器上的用户会话，包括删除所有相关的令牌（包括离线令牌）。这是通过调用/openid-connect/logout端点并传递离线令牌来实现的。

注销对离线令牌的影响

如果执行的是Keycloak服务器注销，那么所有的离线令牌会被删除，应用程序将无法再使用这些令牌来获取新的访问令牌。这一点在Keycloak的文档中有所提及：

“The application can save this offline token in a database or on disk and can use it later even if user is logged out.”

这句话指的是本地客户端注销后的情景，而不是Keycloak服务器注销。

示例

假设我们有一个名为example-app的客户端应用：

1. 获取离线令牌：

   POST /openid-connect/token HTTP/1.1 Host: your-keycloak-server.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=your_authorization_code&client_id=example-app&client_secret=your_secret&redirect_uri=your_redirect_uri&scope=openid offline_access

2. 用户注销（本地客户端注销）：
   此时，用户在example-app中注销，但离线令牌仍然有效。

3. 使用离线令牌获取新访问令牌：

   POST /openid-connect/token HTTP/1.1 Host: your-keycloak-server.com Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=your_offline_token&client_id=example-app&client_secret=your_secret

4. Keycloak服务器注销：

   POST /openid-connect/logout HTTP/1.1 Host: your-keycloak-server.com Content-Type: application/x-www-form-urlencoded refresh_token=your_offline_token&client_id=example-app&client_secret=your_secret

   此时，离线令牌被删除，尝试使用该令牌将返回“Offline user session not found”。

结论

在使用Keycloak的离线令牌时，理解注销的含义非常重要。本地客户端注销不影响离线令牌的使用，而Keycloak服务器注销则会删除所有令牌，包括离线令牌。如果你的应用需要在用户注销后仍能进行某些操作，确保使用的是本地客户端注销方式，或者考虑使用客户端凭证流（Client Credentials Flow）来进行后台API调用。

通过以上分析，我们可以更好地设计和实现基于Keycloak的安全策略，确保用户体验和应用安全性之间的平衡。