Keycloak 22：如何通过GroupProvider集成外部存储中的组？

你的方案完全可行，Keycloak 的 GroupProvider SPI 就是为了实现外部组数据源的无缝集成而设计的，和 UserStorageProvider 思路一致。create() 方法未执行的问题，大概率出在 SPI 注册、配置启用或实现细节上，以下是具体解决步骤：

一、SPI 注册正确性检查 #

1. 必须在项目的 META-INF/services 目录下创建文件 org.keycloak.group.GroupProviderFactory，文件内容为你的工厂类全限定名，例如：

   com.example.provider.MyGroupProviderFactory
   

2. 将打包好的 jar 包放入 Keycloak 的 providers 目录，执行 kc.sh build 后，查看 build 日志，确认是否有类似 Registered group provider: mygroupprovider 的加载记录，没有则说明 SPI 未被正确识别。

二、修正 Factory 类实现细节 #

1. 确保工厂类正确实现 GroupProviderFactory 接口，或继承 AbstractGroupProviderFactory（推荐，已封装默认实现），核心方法必须覆盖：
   • getId()：返回你的 provider ID（即 mygroupprovider）
   • create(KeycloakSession session)：返回自定义 GroupProvider 实例
   • init(Config.Scope config)：用于初始化外部数据库连接、配置读取等操作，该方法会在 create() 之前被调用
2. 示例工厂类代码：

   public class MyGroupProviderFactory implements GroupProviderFactory {
       @Override
       public String getId() {
           return "mygroupprovider";
       }
   
       @Override
       public GroupProvider create(KeycloakSession session) {
           return new MyGroupProvider(session);
       }
   
       @Override
       public void init(Config.Scope config) {
           // 读取外部数据库配置，比如从 keycloak.conf 中获取
           String dbUrl = config.get("db-url");
           // 初始化数据库连接池等资源
       }
   
       @Override
       public void postInit(KeycloakSessionFactory factory) {}
   
       @Override
       public void close() {
           // 释放资源，比如关闭数据库连接池
       }
   }
   

三、正确启用并配置 Provider #

1. 执行 build 命令时，必须显式启用你的 provider，参数格式为 --spi-<provider-type>-<provider-id>-enabled=true：

   kc.sh build --spi-group-provider-mygroupprovider-enabled=true
   

2. 若需要添加自定义配置（如数据库地址、用户名），可以追加参数：

   kc.sh build --spi-group-provider-mygroupprovider-enabled=true --spi-group-provider-mygroupprovider-db-url=jdbc:mysql://xxx:3306/xxx
   

   也可以直接在 keycloak.conf 中添加配置项，再执行 build：

   spi-group-provider-mygroupprovider-enabled=true
   spi-group-provider-mygroupprovider-db-url=jdbc:mysql://xxx:3306/xxx
   

四、GroupProvider 核心方法实现 #

根据业务需求实现 GroupProvider 接口的核心方法，重点覆盖：

• getGroupById(String id)：根据组 ID 从外部数据源查询并返回 GroupModel（可通过 session.group().createGroup() 创建临时模型，或自定义 GroupModel 实现类）
• searchGroups(String search, Integer firstResult, Integer maxResults)：支持组搜索逻辑
• getGroupsByUser(String userId)：返回指定用户所属的外部组
• 若无需写入操作，可忽略 createGroup、deleteGroup 等修改类方法，保持只读集成模式

示例 Provider 代码片段：

public class MyGroupProvider implements GroupProvider {
    private final KeycloakSession session;

    public MyGroupProvider(KeycloakSession session) {
        this.session = session;
    }

    @Override
    public GroupModel getGroupById(String id) {
        // 从外部数据库查询组信息
        ExternalGroup externalGroup = fetchGroupFromDB(id);
        if (externalGroup == null) return null;
        
        // 包装为 Keycloak GroupModel
        GroupModel group = session.group().createGroup(null, externalGroup.getName());
        group.setId(externalGroup.getId());
        group.setSingleAttribute("external-source", "true");
        return group;
    }

    @Override
    public List<GroupModel> searchGroups(String search, Integer firstResult, Integer maxResults) {
        // 实现外部组搜索逻辑
        List<ExternalGroup> externalGroups = searchGroupsFromDB(search, firstResult, maxResults);
        return externalGroups.stream()
                .map(group -> {
                    GroupModel model = session.group().createGroup(null, group.getName());
                    model.setId(group.getId());
                    return model;
                })
                .collect(Collectors.toList());
    }

    @Override
    public List<GroupModel> getGroupsByUser(String userId) {
        // 返回用户关联的外部组
        return Collections.emptyList();
    }

    // 其他接口方法按需实现
}

五、排查 create() 未执行的常见原因 #

1. SPI 未注册：检查 META-INF/services 下的文件是否存在、类名是否正确
2. Provider 未启用：build 命令未添加启用参数，或 keycloak.conf 中未配置启用开关
3. 类路径问题：jar 包未放入 providers 目录，或 build 后未被纳入 Keycloak 运行时类路径
4. 版本兼容：确保代码基于 Keycloak 22 的 API 编写，避免使用已废弃或变更的方法签名

内容的提问来源于stack exchange，提问作者Sebastian.M