Keycloak User Storage SPI社交登录异常：重复账户问题排查

你遇到的核心问题是Keycloak社交登录的流程逻辑：当用户通过Google登录时，Keycloak优先根据社交身份（提供商+用户ID）查找用户，而不是先通过Email匹配。你的SPI仅实现了getUserByEmail，导致Keycloak在第一步查询关联的Google身份时找不到用户，即使后续通过Email找到了用户，仍会触发“关联账户”的提示——因为此时系统认为“Email匹配的本地用户”和“Google身份对应的用户”是两个独立实体。

需要补充实现UserStorageProvider接口的getUserByFederatedIdentity方法，让Keycloak在查询社交身份时，能直接通过SPI找到外部数据库中对应的用户，同时修正现有代码中的问题：

1. 实现getUserByFederatedIdentity方法 #

该方法会在Keycloak处理社交登录时被优先调用，用于根据社交提供商和用户ID查找用户：

@Override
public UserModel getUserByFederatedIdentity(String providerId, String userId, RealmModel realm) {
    // 仅处理Google提供商的情况
    if (!"google".equals(providerId)) {
        return null;
    }

    // 从外部数据库根据Google用户ID查找用户
    CriteriaQuery<ExternalUserModel> query = createCriteriaQuery(AppConstants.GOOGLE_ID, userId);
    try {
        ExternalUserModel externalUser = externalDbSession.createQuery(query).getSingleResult();
        
        // 检查Keycloak本地是否已存在该用户（避免重复创建）
        UserModel existingUser = session.userLocalStorage().getUserById(realm, externalUser.getId());
        if (existingUser != null) {
            // 检查是否已关联Google身份，未关联则添加
            boolean hasFederatedIdentity = session.users().getFederatedIdentities(realm, existingUser)
                    .stream().anyMatch(ident -> "google".equals(ident.getIdentityProvider()) && userId.equals(ident.getUserId()));
            if (!hasFederatedIdentity) {
                FederatedIdentityModel federatedIdentity = new FederatedIdentityModel("google", userId, externalUser.getEmail());
                session.users().addFederatedIdentity(realm, existingUser, federatedIdentity);
            }
            return existingUser;
        }

        // 本地不存在则创建用户并关联Google身份
        UserModel newUser = session.userLocalStorage().addUser(realm, externalUser.getId(), transformUsername(externalUser), true, false);
        newUser.setFederationLink(model.getId());
        newUser.setEmail(externalUser.getEmail());
        newUser.setEnabled(true);
        
        FederatedIdentityModel federatedIdentity = new FederatedIdentityModel("google", userId, externalUser.getEmail());
        session.users().addFederatedIdentity(realm, newUser, federatedIdentity);
        
        return newUser;
    } catch (NoResultException e) {
        // 外部数据库无匹配用户，返回null让Keycloak继续后续流程
        return null;
    } catch (SQLException e) {
        log.error("Error fetching user by federated identity", e);
        return null;
    }
}

2. 修正getUserByEmail代码中的问题 #

你的现有代码存在变量名冲突（ExternalUserModel user和UserModel user重名），同时需要补充身份关联的检查逻辑：

@Override
public UserModel getUserByEmail(String email, RealmModel realm) {
    // 从外部数据库根据Email查找用户
    CriteriaQuery<ExternalUserModel> query = createCriteriaQuery(AppConstants.EMAIL, email);
    try {
        ExternalUserModel externalUser = externalDbSession.createQuery(query).getSingleResult();
        
        // 检查本地是否已存在该用户
        UserModel existingUser = session.userLocalStorage().getUserById(realm, externalUser.getId());
        if (existingUser != null) {
            // 若有GoogleID且未关联，补充关联
            if (externalUser.getGoogleId() != null) {
                boolean hasGoogleIdentity = session.users().getFederatedIdentities(realm, existingUser)
                        .stream().anyMatch(ident -> "google".equals(ident.getIdentityProvider()) && externalUser.getGoogleId().equals(ident.getUserId()));
                if (!hasGoogleIdentity) {
                    FederatedIdentityModel federatedIdentity = new FederatedIdentityModel("google", externalUser.getGoogleId(), email);
                    session.users().addFederatedIdentity(realm, existingUser, federatedIdentity);
                }
            }
            return existingUser;
        }

        // 创建本地用户并关联身份（若有GoogleID）
        UserModel newUser = session.userLocalStorage().addUser(realm, externalUser.getId(), transformUsername(externalUser), true, false);
        newUser.setFederationLink(model.getId());
        newUser.setEmail(email);
        newUser.setEnabled(true);
        
        if (externalUser.getGoogleId() != null) {
            FederatedIdentityModel federatedIdentity = new FederatedIdentityModel("google", externalUser.getGoogleId(), email);
            session.users().addFederatedIdentity(realm, newUser, federatedIdentity);
        }
        
        return newUser;
    } catch (NoResultException nre) {
        // 外部数据库无匹配用户，返回null让Keycloak触发addUser流程
        return null;
    } catch (SQLException e) {
        log.error("Error fetching user by email", e);
        return null;
    }
}

3. 补充addUser方法的逻辑（若未实现） #

当外部数据库和Keycloak本地都无用户时，需要在addUser中同时创建外部用户和本地用户，并关联Google身份：

@Override
public UserModel addUser(RealmModel realm, String username) {
    // 从认证上下文获取Google登录返回的用户信息
    AuthenticationSessionModel authSession = session.getContext().getAuthenticationSession();
    if (authSession == null) {
        return null;
    }
    
    String email = authSession.getClientNote("email");
    String googleId = authSession.getClientNote("google_id"); // 需要在Google身份提供商配置中映射该字段
    
    // 创建外部用户
    ExternalUserModel externalUser = new ExternalUserModel();
    externalUser.setId(UUID.randomUUID().toString());
    externalUser.setUsername(username);
    externalUser.setEmail(email);
    externalUser.setGoogleId(googleId);
    externalDbSession.persist(externalUser);
    externalDbSession.flush();
    
    // 创建本地用户并关联身份
    UserModel newUser = session.userLocalStorage().addUser(realm, externalUser.getId(), username, true, false);
    newUser.setFederationLink(model.getId());
    newUser.setEmail(email);
    newUser.setEnabled(true);
    
    FederatedIdentityModel federatedIdentity = new FederatedIdentityModel("google", googleId, email);
    session.users().addFederatedIdentity(realm, newUser, federatedIdentity);
    
    return newUser;
}

• 确保外部数据库中的googleId字段存储的是Google返回的sub值（即用户的唯一Google身份ID，而非Email），否则getUserByFederatedIdentity无法匹配。
• 在SPI中处理用户创建时，必须检查本地是否已存在该用户，避免重复创建。
• 社交登录场景下，addUser方法需要从认证上下文获取社交提供商返回的用户信息，需在Keycloak的Google身份提供商配置中添加对应的属性映射。

内容的提问来源于stack exchange，提问作者Brijesh Patel