Keycloak自定义GroupStorageProvider已识别但未注册问题求助

问题描述 #

为quay.io/keycloak/keycloak:18.0.0版本创建了自定义GroupStorageProviderFactory及配套GroupStorageProvider，代码如下：

public class XylemGroupStorageProviderFactory
  implements GroupStorageProviderFactory<XylemGroupStorageProvider> {
    static String ID = "xylem-group-storage-provider";
    protected static final List<ProviderConfigProperty> CONFIG_PROPERTIES;
    static {
        CONFIG_PROPERTIES = ProviderConfigurationBuilder.create()
                .property().name("enabled")
                .type(ProviderConfigProperty.BOOLEAN_TYPE)
                .defaultValue("true")
                .add()
                .build();
    }

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

    @Override
    public XylemGroupStorageProvider create(KeycloakSession session, ComponentModel model) {
        GroupStorageProviderModel groupModel = new GroupStorageProviderModel(model);
        groupModel.setEnabled(true);
        return new XylemGroupStorageProvider(session, groupModel);
    }

    @Override
    public List<ProviderConfigProperty> getConfigProperties() {
        return CONFIG_PROPERTIES;
    }
}

该Provider能在Keycloak管理面板的providers页面显示，但工厂类的create方法从未被调用，自定义组存储Provider无法生效。已尝试修改Dockerfile的entrypoint添加启动参数，但不确定参数是否正确：

FROM quay.io/keycloak/keycloak:18.0.0 as builder

ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
ENV KC_FEATURES=authorization,recovery-codes,declarative-user-profile

COPY ./connective-keycloak-password-entropy-18.0.0.jar /opt/keycloak/providers/connective-keycloak-password-entropy-18.0.0.jar
COPY ./argon2-password-hash-provider-2.0.1.jar /opt/keycloak/providers/argon2-password-hash-provider-2.0.1.jar

FROM quay.io/keycloak/keycloak:18.0.0
COPY --from=builder /opt/keycloak/ /opt/keycloak/
WORKDIR /opt/keycloak
ENTRYPOINT ["/bin/sh", "-c", "/opt/keycloak/bin/kc.sh build --db postgres --features-disabled=impersonation --health-enabled=true --spi-group-storage-xylem-group-storage-provider-enabled=true --spi-group-storage=xylem-group-storage-provider && /opt/keycloak/bin/kc.sh start -Dkeycloak.profile.feature.declarative_user_profile=enabled -Dkeycloak.profile.feature.logging=debug --proxy edge"]

解决步骤 #

1. 修正SPI启动参数格式 #

当前的--spi-group-storage=xylem-group-storage-provider参数有误，Group Storage SPI是每个Realm独立配置组件，全局启动参数仅用于启用Provider本身，正确的SPI启用参数仅保留：

--spi-group-storage-xylem-group-storage-provider-enabled=true

无需添加--spi-group-storage=xylem-group-storage-provider，该参数格式适用于全局默认SPI替换，但Group Storage属于组件化SPI，需要在Realm内单独配置实例。

2. 在Realm中添加Group Storage组件 #

这是核心触发步骤：Keycloak不会自动实例化GroupStorageProvider，必须在目标Realm的组件配置中添加该Provider实例：

• 登录Keycloak管理控制台，进入目标Realm
• 左侧菜单选择Configure > Components
• 点击右上角Create，在Provider Type下拉框中选择Group Storage
• 在Provider下拉框中找到你的xylem-group-storage-provider，填写组件名称后点击Save
• 确认组件配置中的Enabled选项为On

完成此操作后，Keycloak才会调用工厂类的create方法实例化Provider。

3. 检查代码与打包配置 #

• 确保自定义Provider的Jar包中包含META-INF/services/org.keycloak.storage.group.GroupStorageProviderFactory文件，文件内容为工厂类的全限定名，例如：

  com.yourpackage.XylemGroupStorageProviderFactory
  

• 确认自定义Provider的Jar包已复制到/opt/keycloak/providers/目录（当前Dockerfile中未包含该Jar的复制指令，需补充）

4. 开启调试日志排查 #

在启动命令中添加日志配置，查看Provider加载细节：
在kc.sh start命令中补充：

-Dlogging.level.org.keycloak.storage=DEBUG

启动后查看日志，确认是否存在Provider加载失败或组件实例化的相关报错信息。

修正后的Dockerfile示例 #

FROM quay.io/keycloak/keycloak:18.0.0 as builder

ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
ENV KC_FEATURES=authorization,recovery-codes,declarative-user-profile

# 复制所有自定义Provider Jar，包括你的组存储Provider
COPY ./connective-keycloak-password-entropy-18.0.0.jar /opt/keycloak/providers/
COPY ./argon2-password-hash-provider-2.0.1.jar /opt/keycloak/providers/
COPY ./your-xylem-group-storage-provider.jar /opt/keycloak/providers/

FROM quay.io/keycloak/keycloak:18.0.0
COPY --from=builder /opt/keycloak/ /opt/keycloak/
WORKDIR /opt/keycloak
ENTRYPOINT ["/bin/sh", "-c", "/opt/keycloak/bin/kc.sh build --db postgres --features-disabled=impersonation --health-enabled=true --spi-group-storage-xylem-group-storage-provider-enabled=true && /opt/keycloak/bin/kc.sh start -Dkeycloak.profile.feature.declarative_user_profile=enabled -Dlogging.level.org.keycloak.storage=DEBUG --proxy edge"]

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