Keycloak 19版本自定义登录提供者无法被调用问题求助

问题情况 #

Keycloak 18里自定义的登录表单提供者（继承FreeMarkerLoginFormsProviderFactory）运行正常，但升级到19之后，CustomProviderFactory的create方法完全没被调用，jboss的deployment.xml配置也都没问题。

示例代码：

public class CustomProviderFactory extends FreeMarkerLoginFormsProviderFactory {
    private FreeMarkerUtil freeMarker;

    @Override
    public LoginFormsProvider create(KeycloakSession session) {
        return new CustomLoginFormsProvider(session, freeMarker);
    }

    @Override
    public void init(Config.Scope config) {
        freeMarker = new FreeMarkerUtil();
    }

    @Override
    public void close() {
        freeMarker = null;
    }

    @Override
    public String getId() {
        return "freemarker";
    }
}

public class CustomLoginFormsProvider extends FreeMarkerLoginFormsProvider {

    public CustomLoginFormsProvider(KeycloakSession session, FreeMarkerUtil freeMarker) {
        super(session, freeMarker);
    }

    @Override
    protected void createCommonAttributes(Theme theme, Locale locale, Properties messagesBundle, UriBuilder baseUriBuilder, LoginFormsPages page) {
        super.createCommonAttributes(theme, locale, messagesBundle, baseUriBuilder, page);
        // 自定义逻辑
    }
}

问题原因 #

Keycloak 19调整了登录表单提供者的加载优先级，内置的freemarker登录提供者现在优先级高于自定义的同名提供者，导致你的自定义工厂类根本没被系统选中执行。

解决办法 #

方法1：更换唯一ID并指定使用 #

1. 修改CustomProviderFactory的getId方法，返回一个独一无二的ID，比如custom-freemarker：

@Override
public String getId() {
    return "custom-freemarker";
}

2. 登录Keycloak控制台，进入对应Realm的Authentication -> Flows，编辑登录流程里的表单环节，将登录表单提供者改为你刚设置的custom-freemarker。

方法2：通过SPI配置强制使用自定义提供者 #

1. 在你的部署包中添加META-INF/services/org.keycloak.authentication.login.LoginFormsProviderFactory文件，内容为自定义工厂类的全限定名，比如：

com.yourcompany.yourpackage.CustomProviderFactory

2. 根据Keycloak运行模式配置优先级：
   • 传统standalone模式：修改standalone.xml

   <subsystem xmlns="urn:jboss:domain:keycloak-server:1.1">
       <spi name="loginForms">
           <!-- 禁用内置的freemarker提供者 -->
           <provider name="freemarker" enabled="false"/>
           <!-- 启用自定义提供者并设置高优先级 -->
           <provider name="custom-freemarker" enabled="true" priority="100"/>
       </spi>
   </subsystem>
   

   • Quarkus模式：修改keycloak.conf

   spi.login-forms.provider=custom-freemarker
   

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