keycloak~keycloak14.0源代码二次开发

2025-10-31 13:29:32 发布 47 浏览

页面报错/反馈

已收藏点赞

本地调试入口

编译keycloak源代码某个包

mvn package -Denforcer.skip=true -Dmaven.test.skip=true
mvn clean install -Dskip=true

部署到私服,建议源码修改后，应该部署到私服，这样其它应用在部署时，也有可以使用修改后的代码了

$ mvn deploy -Denforcer.skip=true -Dmaven.test.skip=true

当用户已经在浏览器登录，在使用自动登录接口（或者之前同时打开两个登录页）这时为了保证用户的登录状态，后面的登录请求会被拦截，跳转到“首页”

如果非iframe的情况，使用下面的代码可以实现问题，在org.keycloak.services.resources.LoginActionsServiceChecks
.checkNotLoggedInYet()和SessionCodeChecks.initialVerifyAuthSession()方法添加302跳转
对于iframe里面的登录页，需要考虑如何在顶级窗口实现重定向,目前添加js重定向解决了这个iframe问题

// TODO: 当用户已经登录了，直接跳到首页
Response.status(302).header(HttpHeaders.LOCATION, "https://www.xxx.com").build();

js重定向解决了同时多个iframe登录框，在其中一个登录，另一个在本iframe重定向问题

修改url中有特殊符号的问题

修改org.keycloak.protocol.oidc.utils.RedirectUtils.removeUrlSpaceParams方法，将特殊符号进行编码

生成token时添加日志

修改code to token的缓存类型

默认使用BasicCache，应该是本地缓存,查通过查看TokenEndpoint，发现是分布式缓存

LOGIN事件的个性化配置

org.keycloak.services.managers.AuthenticationManager的方法nextRequiredAction和actionRequired,添加了LOGIN事件的个性化字段

code_to_token时，去掉了clientId限制

code_to_token时，去掉了clientId必须一致的条件的检验，这样不同客户端在通过code换token时，可以减少与kc交互交次数
方法变更：TokenEndpoint.codeToToken()

code_to_token时对浏览器sessionId操作

当code to token出现错误时，添加了清空浏览器里sessionId在kc的会话信息，但如果是httpclient的调用，咱们是拿不到客户端浏览器的cookie的
Code '%s' already used for userSession
org.keycloak.protocol.oidc.util.OAuth2CodeParser.parseCode这块添加了clientId的日志描述

修改kc管理后台session列表由于信息不全报错的问题

主要是ModelToRepresentation报错了，应该是client_id为空引起的，像refresh_token达到次数会引起会话的client_id为空，但sessionId还是在线的。
这块将异常报错复原了，如果不报错，将会出现大量session从数据库加载，导致数据库崩盘

验证token去掉协议名的限制

对在线token的校验，去掉了https和http的校验，只要后面域名相同就是ISS（Issuer）相同就行，这块在验证token时会用到，另外在适配器集成中，每人请求加载前，也会用到它

调查code码被占用问题（生产了重复的code码)

1 code的生产

2 code的校验

解决同时打开两个登录窗口，在第一个窗口登录后，在第二个窗口再登录一次，会出现“您已经登录”的页面
解决：发生上面的情况后，直接跳到v6首页
- LoginActionsServiceChecks.checkNotLoggedInYet()方法
- SessionCodeChecks.initialVerifyAuthSession()方法

让IdentityProviderMapper实现的类型，自动为社区登录执行delegateUpdateBrokeredUser

修改源代码：org.keycloak.services.resources.updateFederatedIdentity()
添加了代码逻辑，实现了按需自动执行

     //对已有用户进行更新，注意，可能会覆盖用户的其它属性
    FederatedIdentityModel finalFederatedIdentityModel = federatedIdentityModel;
    sessionFactory.getProviderFactoriesStream(IdentityProviderMapper.class)
        .map(IdentityProviderMapper.class::cast)
        .map(mapper -> Arrays.stream(mapper.getCompatibleProviders())
            .filter(type -> Objects.equals(finalFederatedIdentityModel.getIdentityProvider(), type))
            .map(type -> mapper)
            .findFirst()
            .orElse(null))
        .filter(Objects::nonNull)
        .collect(Collectors.toMap(IdentityProviderMapper::getId, Function.identity()))
        .forEach((a, b) -> {
          IdentityProviderMapper target = (IdentityProviderMapper) sessionFactory
              .getProviderFactory(IdentityProviderMapper.class, a);
          IdentityProviderMapperModel identityProviderMapperModel = new IdentityProviderMapperModel();
          identityProviderMapperModel.setConfig(new HashMap());
          identityProviderMapperModel.setSyncMode(IdentityProviderMapperSyncMode.FORCE);
          identityProviderMapperModel.setId(a);
          identityProviderMapperModel.setIdentityProviderMapper(finalFederatedIdentityModel.getIdentityProvider());
          identityProviderMapperModel.setIdentityProviderAlias(finalFederatedIdentityModel.getIdentityProvider());
          try {
            if (!Objects.equals(target.getId(), UsernameTemplateMapper.PROVIDER_ID)) {
              IdentityProviderMapperSyncModeDelegate.delegateUpdateBrokeredUser(session, realmModel, federatedUser,
                  identityProviderMapperModel,
                  context, target);
            }

          } catch (RuntimeException ex) {

          }

        });

添加一个例子，实现社区登录的类型自动存储到用户属性loginType中,getCompatibleProviders()方法中绑定了
IdentityProviderMapper.ANY_PROVIDER，所以在每个社区登录后，它都会被执行
新用户不会绑定这个，已绑定的用户才执行这个方法,原因是syncModel为Force,表示当有用户后，会强制更新它

public class V6UserAttributeMapper extends AbstractJsonUserAttributeMapper {
  public static final String PROVIDER_ID = "v6-user-attribute-mapper";
  private static final String[] cp = new String[] {IdentityProviderMapper.ANY_PROVIDER};

  @Override
  public String[] getCompatibleProviders() {
    return cp;
  }

  @Override
  public String getId() {
    return PROVIDER_ID;
  }

  @Override
  public void updateBrokeredUser(KeycloakSession session, RealmModel realm, UserModel user,
                                 IdentityProviderMapperModel mapperModel, BrokeredIdentityContext context) {
    logger.info("updateBrokeredUser user info...");

    user.setSingleAttribute("loginType", mapperModel.getIdentityProviderAlias());

  }
}

登录后更新用户属性loginType

登录后，将loginType添加到refresh_token中

解决由于kc的refresh_token不支持自定义属性，所以在登录后，将loginType添加到refresh_token中，这样在refresh_token时，就可以获取到loginType了

实现逻辑：将当前loginType添加到当前refresh_token，在下次刷新token时，将refresh_token里的loginType取出来，覆盖到新的access_token里.
org.keycloak.protocol.oidc.TokenManager.validateToken()
org.keycloak.protocol.oidc.TokenManager.build()

用户session_state生成方式

org.keycloak.models.sessions.infinispan.createUserSession()

解决用户浏览器因为丢失keycloak_identity而keycloak_session_id有并且是在线的，导致无法登录的问题

在方法AuthorizationEndpointBase.createAuthenticationSession()添加了判断逻辑，没有keycloak_identity就重新根据session_id再生成一个到cookie里

Cookie cookie = CookieHelper.getCookie(headers.getCookies(), KEYCLOAK_IDENTITY_COOKIE);
if (cookie == null) {
  cookie =
      CookieHelper.getCookie(headers.getCookies(), KEYCLOAK_IDENTITY_COOKIE + CookieHelper.LEGACY_COOKIE);
  if (cookie == null) {
    AuthenticationManager.createLoginCookie(session, realm, user, userSession, session.getContext().getUri(),
        session.getContext().getConnection());
  }
}

关于对loginType和登录事件的修改
请查看TODO: 20230406的注释代码
涉及到以下动作会触发的事件，会添加我们扩展的属性
- 共享登录
- code换token
- 刷新token

关于OTP提供商的调研

OTP提供商的策略：org.keycloak.models.OTPPolicy，目前支持FreeOTP和GoogleAuthenticator

关于keycloak-services项目添加第三方jar包的问题

我们例如将org.infinispan这个包，在kc里也是一个module，引用到keycloak-services项目，它在启动时会报错，告诉找不到这个org.infinispan.Cache类，类似这种类无法找到的错误。

Uncaught server error: java.lang.NoClassDefFoundError: org/infinispan/Cache
        at org.keycloak.keycloak-services@14.0.0//org.keycloak.protocol.oidc.TokenManager.checkTokenValidForIntrospection(TokenManager.java:494)

解决思路，在module.xml中，添加对应的模块即可

从keycloak容器里将/opt/jboss/keycloak/modules/system/layers/keycloak/org/keycloak/keycloak-core/main/module.xml复制出来，在文件的dependencies节点下添加依赖，如

修改Dockerfile文件，将这个module.xml文件也复制到上面的容器目录，覆盖原来的文件
重新构建镜像，启动容器，问题解决

自动登录接口同一浏览器添加踢出之前登录的逻辑

org.keycloak.protocol.AuthorizationEndpointBase.handleBrowserAuthenticationRequest()

从carsi网站过来的用户，会带有carsi-auto这个关键字，也应该要踢出之前的登录

org.keycloak.broker.oidc.AbstractOAuth2IdentityProvider.Endpoint.authResponse()

刷新token和通过code换token逻辑中，添加infinispan缓存的逻辑，键key是sessionId+clientId，作用是当用户的角色变更后，用户校验token直接返回false，让迫使用户重新去刷新token

// TODO: xxx_user_modify_role 需要添加逻辑，去检索事件中是否包括了权限变更的用户

验证token: org.keycloak.protocol.oidc.TokenManager.checkTokenValidForIntrospection()
~~刷新token: org.keycloak.protocol.oidc.endpoints.TokenEndpoint.refreshTokenGrant~~
,这块因为相同的event对象，所以代码迁移到keycloak-services-event-kafka
~~code换token: org.keycloak.protocol.oidc.endpoints.TokenEndpoint.codeToToken()~~
,这块因为相同的event对象，所以代码迁移到keycloak-services-event-kafka

用户权限更新后，通和逻辑整理

kc服务端收到REALM_ROLE_MAPPING或者USER_ROLE_CHANGE事件后，向infinispan缓存里添加一个key，key是
xxx_user_modify_role_{userId},value是空
它有缓存有效期与access_token的相同，目前为30分钟
当用户进行code换token或者刷新token时，根据当前用户id，去上面缓存中找，如果查找到，说明这个用户的权限发生了变更
找到后，向这个缓存xxx_user_modify_role_{userId}添加value，value格式是{sessionId}_{clientId}，就是用户在哪个浏览器
哪个客户端访问
当用户调用验证token接口时，如果在xxx_user_modify_role_{userId}中没有找到这个value{sessionId}_{clientId}，就验证失败
当验证失败后，返回401，用户再去刷新token，向xxx_user_modify_role_{userId}中添加对应的value, 保持下次验证会成功

获取IP地址的方法修改

// TODO: 优化登录事件中，获取ipAddress的逻辑，改为real-ip有限

org.keycloak.events.EventBuilder.ipAddress()进行了重新赋值
org.keycloak.services.resources.admin.AdminEventBuilder.AdminEventBuilder()初始化时，使用real-ip

验证token逻辑的抛下，解析session idle和session max的逻辑

org.keycloak.services.managers.AuthenticationManager.isSessionValid
SessionTimeoutHelper.IDLE_TIMEOUT_WINDOW_SECONDS是个时间戳口，它是120秒

  public static boolean isSessionValid(RealmModel realm, UserSessionModel userSession) {
    if (userSession == null) {
        logger.debug("No user session");
        return false;
    }
    int currentTime = Time.currentTime();

    // Additional time window is added for the case when session was updated in different DC and the update to current DC was postponed
    int maxIdle = userSession.isRememberMe() && realm.getSsoSessionIdleTimeoutRememberMe() > 0 ?
            realm.getSsoSessionIdleTimeoutRememberMe() : realm.getSsoSessionIdleTimeout();
    int maxLifespan = userSession.isRememberMe() && realm.getSsoSessionMaxLifespanRememberMe() > 0 ?
            realm.getSsoSessionMaxLifespanRememberMe() : realm.getSsoSessionMaxLifespan();

    boolean sessionIdleOk =
            maxIdle > currentTime - userSession.getLastSessionRefresh() - SessionTimeoutHelper.IDLE_TIMEOUT_WINDOW_SECONDS;
    boolean sessionMaxOk = maxLifespan > currentTime - userSession.getStarted();
    return sessionIdleOk && sessionMaxOk;
}

session idle和session max的逻辑生效，如果修改refresh_token生成时的校验逻辑

org.keycloak.protocol.oidc
.TokenManager.refreshAccessToken()方法中的代码,将verifyRefreshToken方法参数中的checkExpiration改成false
// TODO: 完善实现了在线校验时，session idle和session max的功能

session idle(空闲过期时间）和session max（最大过期时间）不相等时，产生的问题

描述与解决思路

session idle会作为刷新token的过期时间
当这个时间到达后，不能再刷新token了，但是，session还是在线的
是否需要在到达这个时间后，将会话删除？
如果真要删除的话，可能产生的问题就是session max的时间还没到，但是session已经被删除了，这样就会导致session max的时间不准确了
但如果session idle到达，并且token没有成功刷新，这说明用户空闲了，这时session是可以删除的，与4不矛盾
解决方法
*[x] 在session idle到达后，将session删除，应该就解决问题了
*[x] 或者在生成code之前，判断它的session idle是否到期，如果到期，将会话删除，不能生成code

用户会话过期，清理用户会话的逻辑调整

org.keycloak.services.scheduled.ScheduledTaskRunner # 默认900秒(15分钟)执行一次
- org.keycloak.services.scheduled.ClearExpiredUserSessionsTask
  - org.keycloak.models.map.authSession.removeExpired
  - 需要添加空闲过期时间的判断，如果到期，就删除会话
  - 这块需要看如何手动清除，因为默认的，infinispan中的session，有自己的过期时间，按着过期时间自动清除的
  - 咱们相当于，如何让它按着咱们的时间（这个时间经过了session idle的时间）来清除的
通过上面的分析，直接从infinispan中获取过期的session，并删除不太可能，人家通知初始化的过期时间自行维护的，而且这种过期时间，是session
max，而咱们的过期时间是可变的，它可能是一个session idle，也可能是session max，这与用户是否在idle时间内是否有操作有关

这种定时器，可能是为了mysql中存储的离线token用的，可查看offline_user_session相关的内容
我们如果在生成code时，添加一个判断，判断这个session idle是否到期，如果到期，就删除会话，不能生成code

生成code时，添加session idle的判断

如果不添加这个判断，将会出现的问题是，当session idle和session max设置不同时，当session
idle到期后，用户的会话不会被删除，导致刷新token和申请code码换token，两块产生的token逻辑不一样，最终效果就是，code可以换回来token，但token在校验时是
session not active这样的错误。
org.keycloak.protocol.AuthorizationEndpointBase.createAuthenticationSession()方法

修改org.keycloak.theme.DefaultThemeSelectorProvider文件getThemeName()方法，添加了url中皮肤参数theme

MultivaluedMap query = session.getContext().getUri().getQueryParameters();
if(query.

containsKey("theme")){
name=query.

getFirst("theme");
}else{
        ｝

登录跨域支持

org.keycloak.protocol.oidc.endpoints.TokenEndpoint.resourceOwnerPasswordCredentialsGrant()，返回值添加跨域代码

return cors.builder(Response.ok(res, MediaType.APPLICATION_JSON_TYPE)).

allowAllOrigins().

build();

登录回调地址中添加loginType这个参数

org.keycloak.services.resources.IdentityBrokerService.finishBrokerAuthentication()方法添加对loginType的操作
org.keycloak.protocol.oidc.OIDCLoginProtocol.authenticated()方法中，获取loginType，并添加到回调路径的URL参数中

社区登录成功后，绑定用户信息，修改FEDERATED_IDENTITY_LINK的内容

org.keycloak.services.resources.IdentityBrokerService.afterFirstBrokerLogin方法
添加自定义事件元素：event.detail(Details.IDENTITY_PROVIDER_USERNAME, context.getBrokerUserId());

刷新token时，如果用户有required action，抛出异常

org.keycloak.protocol.oidc.TokenManager.validateToken()方法

    //TODO:刷新token时，如果用户有required action，抛出异常
    if (user.getRequiredActionsStream().findAny().isPresent()) {
      throw new OAuthErrorException(OAuthErrorException.INVALID_GRANT, "User has required action",
          "User has required action");
    }

社区登录state的自定义

社区登录回调state参数，支持4个参数

org.keycloak.broker.provider.util.IdentityBrokerState类中encoded方法，将
String[] decoded = DOT.split(encodedState, 4);从3改成4

建立社区登录地址时添加自定义state参数

AbstractOAuth2IdentityProvider类中createAuthorizationUrl方法，修改state参数的拼接

 String state = request.getState().getEncoded();
    if(request.

getAuthenticationSession().

getAuthNote("g") !=null&&
        request.

getAuthenticationSession().

getAuthNote("g").

trim() !=""){
state =state +"."+request.

getAuthenticationSession().

getAuthNote("g");
    }

在认证成功后federatedIdentityContext上下文添加参数

AbstractOAuth2IdentityProvider类中Endpoint.authResponse方法，再返回之前为federatedIdentity添加groupId参数

// 添加集团代码
String[] decoded = DOT.split(state, 4);
if(decoded.length ==4){
        federatedIdentity.

setUserAttribute("groupId",decoded[3]);
}

登录超时的提示语调整

keycloak-themes/themes/base/login/messages/messages_en.properties文件
修改loginTimeout的值即可

社区登录页{provider}/login页添加idp和login_type参数

org.keycloak.services.Urls类identityProviderAuthnRequest()方法，添加idp参数的追加
org.keycloak.authentication.authenticators.browser.IdentityProviderAuthenticator类中redirect()
方法构建登录页重定向参数，添加loginType和idp两个参数

/auth/realms/xxx/protocol/openid-connect/userinfo接口添加session_state属性返回值

org.keycloak.protocol.oidc.OIDCLoginProtocolService类中的issueUserInfo()方法
添加跨域支持allowedOrigins("*")
解析当前token，并添加session_state

claims.put("session_state", userSession.getId());// 添加当前的session信息

刷新token时，出现`Session not active`或者`Invalid refresh token`

Session not active 表示用户的session已经过期了，需要重新登录，返回400
Invalid refresh token 表示refresh token不正确，可能token被篡改了，需要重新登录，返回400
刷新token时，只有一种情况会返回401，就是client_secret错误时，Client secret not provided in request
org.keycloak.protocol.oidc.TokenEndpoint.refreshTokenGrant()方法,添加refresh_token验证不通过，会走这个catch逻辑,大多数情况httpcode都是400

catch (OAuthErrorException e) {
      logger.trace(e.getMessage(), e);
      // KEYCLOAK-6771 Certificate Bound Token
      if (MtlsHoKTokenUtil.CERT_VERIFY_ERROR_DESC.equals(e.getDescription())) {
        event.error(Errors.NOT_ALLOWED);
        throw new CorsErrorResponseException(cors, e.getError(), e.getDescription(), Response.Status.UNAUTHORIZED);
      } else {
        event.error(Errors.INVALID_TOKEN);
        throw new CorsErrorResponseException(cors, e.getError(), e.getDescription(), Response.Status.BAD_REQUEST);
      }
 ｝

社区登录添加loginType为社区的idp

情况一，未绑定用户，走first flow
情况二，绑定了用户，下次再登录，会走after flow

first flow

org.keycloak.services.resources.IdentityBrokerService.authenticated()方法，添加代码

authenticationSession.setUserSessionNote("loginType",context.getIdpConfig().getProviderId());

after flow