6.4. 离线访问

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

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

刷新令牌和离线令牌之间的区别是离线令牌永远不会过期，且不会受到 SSO Session Idle timeout 和 SSO Session Max lifespan 的影响。用户退出后，离线令牌有效。您必须每 30 天或 Offline Session Idle 指定的天数使用离线令牌进行刷新令牌操作。

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

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

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

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

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

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

默认情况下，Red Hat build of Keycloak 会将其内部缓存限制为离线用户和离线客户端会话，这样可减少离线会话的总内存用量。根据需要，从内存驱除的项目将从数据库按需加载。要为缓存设置不同的大小，请编辑 Keycloak 的缓存配置文件，为这些缓存设置 < memory max-count="..."/& gt;。

如果您禁用了 persistent-user-sessions 功能，可以使用配置选项降低内存要求，以缩短导入离线会话的时间。此类会话将在指定的生命周期之后从 Infinispan 缓存中驱除，但仍然在数据库中可用。这将降低内存消耗，特别是对于有大量离线会话的部署。

要为离线用户会话指定 lifespan 覆盖，请使用以下参数启动红帽构建的 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>