Keycloak session和token配置经验总结

Session配置

配置项说明

配置项	描述
SSO Session Idle	此设置仅适用于 OIDC 客户端。 如果用户处于非活动状态的时间超过此超时，则用户会话将失效。 当客户端请求身份验证或发送刷新令牌请求时，此超时值将重置。 Keycloak 在会话失效生效之前为空闲超时添加了一个时间窗口。
SSO Session Max	用户会话过期之前的最长时间。
SSO Session Idle Remember Me	此设置类似于标准 SSO 会话空闲（SSO Session Idle）配置，但特定于启用“记住我”的登录。 用户在登录时单击“记住我”时可以指定更长的会话空闲超时。此设置是可选配置，如果其值不大于零，则它使用与 SSO 会话空闲配置（SSO Session Idle）相同的空闲超时。
SSO Session Max Remember Me	此设置类似于标准 SSO 会话最大值（SSO Session Max），但特定于“记住我”登录。 用户在登录时单击“记住我”时可以指定更长的会话。此设置是可选配置，如果其值不大于零，则它使用与 SSO 会话最大配置（SSO Session Max）相同的会话生命周期。
Client Session Idle	客户端会话的空闲超时。 如果用户处于非活动状态的时间超过此超时，则客户端会话将失效，并且刷新令牌请求会导致空闲超时。 此设置永远不会影响一般 SSO 用户会话，这是唯一的。 请注意，SSO 用户会话是零个或多个客户端会话的父会话，为用户登录的每个不同客户端应用程序创建一个客户端会话。此值应指定比 SSO 会话空闲更短的空闲超时。 用户可以在“高级设置”客户端选项卡中为各个客户端覆盖它。 此设置是可选配置，当设置为零时，将使用与在 SSO 会话空闲配置（SSO Session Idle）相同的空闲超时。
Client Session Max	客户端会话以及刷新令牌过期和失效之前的最长时间。 与上一个选项一样，此设置永远不会影响 SSO 用户会话，并且应指定比 SSO 会话最大值更短的值。 用户可以在“高级设置”客户端选项卡中为各个客户端覆盖它。 此设置是可选配置，当设置为零时，将使用与在 SSO 会话最大配置（SSO Session Max）相同的最大超时。
Offline Session Idle	此设置用于离线访问。 在 Keycloak 撤销其离线令牌之前会话保持空闲的时间。 Keycloak 在会话失效生效之前为空闲超时添加了一个时间窗口。 请参阅本节后面的注释。
Offline Session Max Limited	此设置用于离线访问。 如果启用此标志，则无论用户活动如何，离线会话最大值都可以控制离线令牌保持活动的最长时间。 如果该标志为“禁用”，则离线会话永远不会根据生命周期过期，只会根据空闲过期。 激活此选项后，可以配置离线会话最大值（领域级别的全局选项）和客户端离线会话最大值（高级设置选项卡中的特定客户端级别选项）。
Offline Session Max	这个设置是针对离线访问的，是Keycloak撤销对应离线token的最长时间。 此选项控制离线令牌保持活动状态的最长时间，无论用户活动如何。
Client Offline Session Idle	客户端离线会话在过期之前允许空闲的时间。 当客户端离线会话过期时，离线令牌将失效。 如果未设置，则使用离线会话空闲值（Offline Session Idle）。
Client Offline Session Max	客户端离线会话过期之前的最长时间。 当客户端离线会话过期时，离线令牌将失效，如果未设置，则使用离线会话最大值（Offline Session Max）。
Login timeout	登录必须花费的总时间。 如果身份验证花费的时间超过此时间，则用户必须重新启动身份验证过程。
Login action timeout	用户在身份验证过程中可以在任何一页上花费的最长时间

Token配置

 配置项说明

配置项	描述
Default Signature Algorithm	用于为领域分配令牌的默认算法。
Revoke Refresh Token	启用后，刷新令牌或者离线令牌将只能使用一次，Keycloak 将撤销刷新令牌并颁发客户端必须使用的另一个新的刷新令牌。 此操作适用于执行刷新令牌流的 OIDC 客户端。
Access Token Lifespan	当 Keycloak 创建 OIDC 访问令牌时，该值控制令牌的生命周期。
Access Token Lifespan For Implicit Flow	对于隐式流程，Keycloak 不提供刷新令牌。 隐式流创建的访问令牌存在单独的超时。
Client login timeout	客户端必须在 OIDC 中完成授权代码流程之前的最长时间。
User-Initiated Action Lifespan	用户操作权限到期之前的最长时间。 保持该值较短，因为用户通常会对自行创建的操作做出快速反应。
Default Admin-Initiated Action Lifespan	管理员发送给用户的操作权限到期之前的最长时间。 保留此值较长，以便管理员可以向离线用户发送电子邮件。 管理员可以在颁发令牌之前覆盖默认超时。
Email Verification	指定电子邮件验证的独立超时。
IdP account email verification	指定 IdP 帐户电子邮件验证的独立超时。
Forgot password	指定忘记密码的独立超时。
Execute actions	指定执行操作的独立超时。

客户端Session和Token配置

在客户端配置中的高级配置中，可以对当前客户端的session和token进行配置，优先级高于领域（realm）级别的全局配置。

关于空闲超时

对于空闲超时，存在会话处于活动状态的两分钟时间窗口。 例如，当您将超时设置为 30 分钟时，会话将在 32 分钟后到期。
对于集群和跨数据中心环境中的某些场景，此操作是必要的，在这些场景中，令牌在过期前一小段时间在一个集群节点上刷新，而其他集群节点错误地认为会话已过期，因为它们尚未收到有关会话的消息。 从刷新节点刷新成功。

关于访问令牌（access_token）的有效期 

访问令牌（access_token）的有效期（expires_in）一般情况下是由访问令牌生命周期（Access Token Lifespan）决定的。但是如果用户会话最长时间（SSO Session Max）小于访问令牌生命周期（Access Token Lifespan），有效期将使用用户会话最长时间（SSO Session Max）的配置。

通常情况下，用户会话最长时间（SSO Session Max）会远远大于访问令牌生命周期（Access_Token_Lifespan）。在用户会话周期内，访问令牌（access_token）临过期时，可以使用刷新令牌（refresh_token）来获取新的访问令牌（access_token）。

关于刷新令牌（refresh_token）的有效期

刷新令牌（refresh token）的有效期（refresh_expires_in）是由用户会话空闲超时（SSO Session Idle）和客户端用户会话空闲超时（Client SSO Session Idle）决定的，有效期取决于两个配置项的较小值。但是如果用户会话最长时间（SSO Session Max）小于用户会话空闲超时（SSO Session Idle）和客户端用户会话空闲超时（Client SSO Session Idle），有效期将使用用户会话最长时间（SSO Session Max）的配置。

关于用户会话（session）

如上图，每条用户会话都会有四个属性：

属性	描述
IP Adress	ip地址
Started	开始时间
Last Access	上一次访问时间
Clients	当前session属于哪个客户端
Logout	退出登陆

更新Last Access时间

用户会话周期内，每次使用refresh_token获取新的access_token时，都会更新用户会话的Last Access时间。

什么情况下会主动清空Clients

如果客户端用户会话最长时间（Client Session Max）小于用户会话最长时间（SSO Session Max），客户端Session过期后，会清空用户会话的Clients属性。

退出登陆Logout

如果用户在OIDC客户端主动退出登陆或者点击会话列表中的登出按钮（Logout），用户会话会立即失效并清除。

清除用户会话

当用户会话（session）过期后，用户必须重新发起身份认证以获得新的用户会话（session），而且旧的用户会话（session）会从sessions列表删除。

关于离线访问（Offline access）

在离线访问登录期间，客户端应用程序请求离线令牌而不是刷新令牌。 客户端应用程序会保存此离线令牌，并在用户注销时将其用于将来的登录。 如果您的应用程序需要代表用户执行离线操作（即使用户不在线），则此操作非常有用。 例如定期的数据备份。

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

离线令牌和刷新令牌的区别

离线令牌和刷新令牌之间的区别在于，离线令牌永不过期，并且不受会话空闲超时（SSO Session Idle）和会话最大时间（SSO Session Max）的影响。 离线令牌在用户注销或服务器重新启动后依然有效。 但是您必须至少每三十天（Offline Session Idle的默认值）使用一次离线令牌进行刷新令牌操作，或者使用离线会话空闲值（Offline Session Idle）。

如果您启用离线会话最大限制（Offline Session Max Limited），离线令牌默认将在 60 天后过期，即使您使用离线令牌进行刷新令牌操作也是如此。 您可以在管理控制台中更改离线会话最大限制（Offline Session Max）的值。

如果启用“撤消刷新令牌”选项（Revoke Refresh Token option），则每个离线令牌只能使用一次。 刷新后，您必须存储刷新响应中的新离线令牌，而不是之前的离线令牌。

客户端离线会话空闲超时和最大超时（Client Offline Session Idle 和 Client Offline Session Max）

使用离线访问时，可以在客户端级别覆盖客户端空闲和最大超时。 客户端“高级设置”选项卡中的“客户端离线会话空闲（Client Offline Session Idle）”和“客户端离线会话最大（Client Offline Session Max）”选项允许您为特定应用程序设置更短的离线超时。 请注意，客户端会话值还控制刷新令牌（refresh_token）过期时间，但它们永远不会影响全局离线用户 SSO 会话。 仅当在领域级别启用“离线会话最大限制（Offline Session Max Limited）”时，才会在客户端中评估“客户端离线会话最大超时（Client Offline Session Max）”选项。

撤销离线令牌

用户可以在用户帐户控制台中查看和撤销 Keycloak 授予他们的离线令牌。

管理员可以在管理控制台的“同意（Consents）”选项卡中撤销单个用户的离线令牌。

管理员可以在每个客户端的“离线访问”选项卡中查看颁发的所有离线令牌。 管理员可以通过设置撤销策略来撤销离线令牌。

 颁发离线令牌条件

用户必须具有realm领域级offline_access 角色的角色映射。这是默认完成的。

客户端也必须在其scope范围内拥有该角色。 客户端必须将offline_access 客户端范围作为可选客户端范围（Optional Client Scopes ）添加到其角色中，这些也是默认完成的。

获取离线令牌

客户端在向Keycloak发送授权请求时，可以通过添加参数scope=offline_access来请求离线令牌。

当您使用 Keycloak OIDC 客户端适配器访问应用程序的安全 URL（例如，http://localhost:8080/customer-portal/secured?scope=offline_access）时，Keycloak OIDC 客户端适配器会自动添加此参数。 如果您在身份验证请求正文中包含scope=offline_access，则直接访问授予和服务帐户支持离线令牌。

离线会话预加载

除了 Infinispan 缓存之外，离线会话还存储在数据库中，这意味着即使在服务器重新启动后它们也可用。 默认情况下，在Keycloak服务器启动期间，离线会话不会从数据库预加载到 Infinispan 缓存中，因为如果需要预加载许多离线会话，这种方法就会有缺点。 它可以显着减慢服务器的启动时间。 因此，默认情况下，离线会话是从数据库延迟获取的。

但是，Keycloak 可以配置为在服务器启动期间将离线会话从数据库预加载到 Infinispan 缓存中。 可以通过将 userSessions SPI 中的 preloadOfflineSessionsFromDatabase 属性设置为 true 来实现。

以下示例显示如何配置离线会话预加载。

bin/kc.[sh|bat] start --spi-user-sessions-infinispan-preload-offline-sessions-from-database=true

关于临时会话（Transient session）

您可以在 Keycloak 中进行临时会话。 使用临时会话时，Keycloak 在身份验证成功后不会创建用户会话。 Keycloak 在成功验证用户身份的当前请求范围内创建一个暂时的临时会话。 Keycloak 可以在身份验证后使用临时会话来运行协议映射器。

当使用临时会话颁发令牌时，令牌的 sid 和 session_state 通常为空。 因此，在临时会话期间，客户端应用程序无法刷新令牌或验证特定会话。 有时这些操作是不必要的，因此您可以避免持久用户会话的额外资源使用。 此会话可节省性能、内存和网络通信（在集群和跨数据中心环境中）资源。

此时，仅在服务帐户身份验证（service account authentication）期间自动使用临时会话，并禁用令牌刷新。 请注意，除非客户端显式启用“使用刷新令牌进行客户端凭据授权（Use refresh tokens for client credentials grant）”，否则在服务帐户身份验证（service account authentication）期间将自动禁用令牌刷新。