Keycloak 22.0.4自定义认证类替代AbstractUsernameFormAuthenticator遇阻求助

我在Keycloak 22.0.4版本中尝试用自定义类替换系统自带的AbstractUsernameFormAuthenticator类，已经完成以下操作：

• 创建自定义Provider
• 生成Jar包
• 将Jar包放入Keycloak的provider目录

但自定义认证功能未生效，请问我遗漏了哪些步骤？

相关代码 #

自定义认证类 #

public class CustomAuthenticator extends UsernamePasswordForm {

    @Override
    protected String disabledByBruteForceError() {
        return Messages.ACCOUNT_TEMPORARILY_DISABLED;
    }
}

自定义认证工厂类 #

public class CustomAuthenticatorFactory implements AuthenticatorFactory, ConfigurableAuthenticatorFactory {

    public static final String PROVIDER_ID = "custom-authenticator";
    private static final CustomAuthenticator SINGLETON = new CustomAuthenticator();

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

    @Override
    public String getDisplayType() {
        return "Custom Authenticator";
    }

    @Override
    public String getReferenceCategory() {
        return null;
    }

    @Override
    public boolean isConfigurable() {
        return false;
    }

    @Override
    public AuthenticationExecutionModel.Requirement[] getRequirementChoices() {
        return Arrays.asList(AuthenticationExecutionModel.Requirement.REQUIRED).toArray(new AuthenticationExecutionModel.Requirement[0]);
    }

    @Override
    public boolean isUserSetupAllowed() {
        return false;
    }

    @Override
    public String getHelpText() {
        return null;
    }

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

    @Override
    public void init(Config.Scope scope) {

    }

    @Override
    public void postInit(KeycloakSessionFactory keycloakSessionFactory) {

    }

    @Override
    public void close() {

    }

    @Override
    public Authenticator create(KeycloakSession session) {
        return SINGLETON;
    }
}

resources/META-INF/services/org.keycloak.authentication.AuthenticatorFactory 文件内容 #

com.identicum.keycloak.CustomAuthenticatorFactory

jboss-deployment-structure.xml 文件内容 #

<?xml version="1.0" encoding="UTF-8"?>
<jboss-deployment-structure>
    <deployment>
        <module-alias name="deployment.keycloak-custom-authenticator"/>
        <dependencies>
            <module name="org.keycloak.keycloak-core"/>
            <module name="org.keycloak.keycloak-server-spi"/>
            <module name="org.keycloak.keycloak-server-spi-private"/>
            <module name="org.keycloak.keycloak-services"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>

遗漏的关键步骤 #

1. 重启Keycloak服务：Keycloak不会自动加载新增的provider，必须重启服务才能识别新Jar包。
2. 替换认证流程中的默认认证器：
   • 登录Keycloak控制台，进入目标Realm
   • 切换到「Authentication」→「Flows」页面
   • 复制一个现有流程（比如「Browser」流程），避免修改系统默认流程
   • 展开复制后的流程，找到「Username Password Form」步骤
   • 点击该步骤的「Actions」→「Replace」，选择你的「Custom Authenticator」
   • 保存流程，并将该流程设置为当前Realm的默认认证流程
3. 验证依赖版本一致性：确保编译时使用的Keycloak依赖版本与运行环境的22.0.4完全一致，版本不匹配会导致类加载失败。
4. 检查Provider加载日志：查看Keycloak启动日志，搜索CustomAuthenticatorFactory类名，确认是否有加载成功的记录；如果出现ClassNotFound或NoClassDefFoundError，说明依赖缺失或打包不完整。
5. 确认打包完整性：检查Jar包内是否包含META-INF/services/org.keycloak.authentication.AuthenticatorFactory文件，路径和内容必须完全正确，Keycloak通过这个文件发现自定义Provider。

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