6.4. 离线访问

在 离线访问 登录过程中，客户端应用程序会请求离线令牌，而不是刷新令牌。客户端应用保存此离线令牌，并在用户注销时将其用于以后登录。如果您的应用程序需要代表用户执行离线操作，即使用户没有在线，这个操作也会很有用。例如，常规数据备份。

客户端应用程序负责将离线令牌保留在存储中，然后使用它从红帽构建的 Keycloak 服务器检索新的访问令牌。

刷新令牌和离线令牌之间的区别在于离线令牌永远不会过期，且不受 SSO Session Idle timeout 和 SSO Session Max lifespan 的影响。在用户注销或服务器重新启动后，离线令牌有效。您必须每 30 天或 Offline Session Idle 指定的天数使用离线令牌进行刷新令牌操作。

如果您启用 离线 Session Max Limited，则离线令牌会在 60 天后过期，即使您使用离线令牌进行刷新令牌操作。您可以在管理门户中更改这个值 Offline Session Max。

使用离线访问时，客户端闲置和最大超时可在 客户端级别 覆盖。在 client Advanced Settings 选项卡中，选项 Client Offline Session Idle and Client Offline Session Max 可让您为特定应用程序有较短的离线超时。请注意，客户端会话值也控制刷新令牌过期，但它们永远不会影响全局离线用户 SSO 会话。只有在 realm 级别中 Offline Session Max Limited 被设置为 Enabled 时，选项 Client Offline Session Max 才会被评估。

如果启用 Revoke Refresh Token 选项，则只能使用每个离线令牌一次。刷新后，您必须从刷新响应而不是上一个令牌保存新的离线令牌。

用户可以在用户帐户控制台中查看和撤销红帽构建的 Keycloak 的 离线令牌。管理员可以在 Consents 选项卡中为单个用户撤销离线令牌。管理员可以查看每个客户端的离线 访问 选项卡中发出的所有离线令牌。管理员可以通过设置 吊销策略 来撤销离线令牌。

要发出离线令牌，用户必须有 realm-level offline_access 角色的角色映射。客户端还必须在其范围内具有该角色。客户端必须添加一个 offline_access 客户端范围作为 Optional 客户端范围 到该角色，这默认为完成。

当向红帽构建的 Keycloak 发送授权请求时，客户端可以通过添加参数 scope=offline_access 来请求离线令牌。当您用来访问应用程序的安全 URL （如 http://localhost:8080/customer-portal/secured?scope=offline_access）时，红帽构建的 Keycloak OIDC 客户端适配器会自动添加此参数。如果您在身份验证请求正文中包含 scope=offline_access，则 Direct Access Grant 和 Service Accounts 支持离线令牌。

离线会话与存储在数据库中的 Infinispan 缓存旁边。每当红帽构建的 Keycloak 服务器被重启或离线会话都会从 Infinispan 缓存驱除时，它仍然在数据库中可用。一旦尝试访问离线会话，都将从数据库加载会话，还会将其导入到 Infinispan 缓存。为降低内存要求，我们引入了一个配置选项，用于缩短导入的离线会话的生命周期。这些会话将在指定生命周期后从 Infinispan 缓存驱除，但仍然在数据库中可用。这将降低内存消耗，特别是对于有大量离线会话的部署。目前，离线会话生命周期覆盖被默认禁用。要为离线用户会话指定生命周期覆盖，请使用以下参数启动红帽构建的 Keycloak 服务器：

--spi-user-sessions-infinispan-offline-session-cache-entry-lifespan-override=<lifespan-in-seconds>

与离线客户端会话类似：

--spi-user-sessions-infinispan-offline-client-session-cache-entry-lifespan-override=<lifespan-in-seconds>