本文详细讲解如何在 keycloak 中实现基于自定义字段（如 fielda、fieldb、hash）的认证逻辑，替代默认的 username/password 流程，并通过 authenticator + authenticatorfactory 注册、部署及绑定到认证流。
要在 Keycloak 中实现完全自定义的认证流程（例如接收 fieldA、fieldB 和 hash 参数完成登录，而非标准的 username/password），仅实现 Authenticator 接口是不够的——必须配套提供 AuthenticatorFactory，完成 SPI 注册、服务发现与流程集成。以下是完整、可落地的操作步骤：
✅ 1. 实现核心认证逻辑（Authenticator）
你的 CustomAuthenticator 需从请求中提取自定义参数，执行业务校验（如签名验证、令牌比对、第三方系统调用等），并最终设置用户上下文：
public class CustomAuthenticator implements Authenticator {
@Override
public void authenticate(AuthenticationFlowContext context) {
// 从表单或 JSON body 中获取自定义参数（Keycloak 默认解析 application/x-www-form-urlencoded）
String fieldA = context.getHttpRequest().getDecodedFormParameters().getFirst("fieldA");
String fieldB = context.getHttpRequest().getDecodedFormParameters().getFirst("fieldB");
String hash = context.getHttpRequest().getDecodedFormParameters().getFirst("hash");
// ✅ 业务校验逻辑（示例：简单哈希匹配，生产环境请替换为安全验证）
if (isValid(fieldA, fieldB, hash)) {
// 根据 fieldA 查找对应用户（例如 fieldA 是手机号、设备ID 或外部账号）
UserModel user = context.getSession().users()
.getUserByUsername(fieldA, context.getRealm()); // 或使用 getUserByFederatedIdentity 等
if (user != null) {
context.setUser(user);
context.success(); // 认证成功 → 进入下一步（如颁发 token）
return;
}
}
// ❌ 认证失败：返回标准化错误（前端可捕获）
context.failure(AuthenticationFlowError.INVALID_USER);
// 可选：添加错误提示（需配合 message bundle）
context.getEvent().error(Errors.INVALID_USER_CREDENTIALS);
}
private boolean isValid(String fieldA, String fieldB, String hash) {
// 替换为实际校验逻辑，例如 HMAC-SHA256(fieldA + fieldB + secret) == hash
return "expected-hash".equals(hash);
}
@Override
public void action(AuthenticationFlowContext context) {
// 此方法用于处理 POST 表单提交后的二次操作（如 OTP 提交），本场景通常无需重写
authenticate(context);
}
@Override
public boolean requiresUser() {
return false; // 若认证过程不依赖已知用户（如先注册再登录），可设为 false；若需查用户则建议 true
}
@Override
public boolean configuredFor(KeycloakSession session, RealmModel realm, UserModel user) {
return true; // 本 Authenticator 不依赖用户级配置，始终可用
}
@Override
public void setRequiredActions(KeycloakSession session, RealmModel realm, UserModel user) {
// 如需强制用户后续执行动作（如首次登录改密），在此添加
}
@Override
public void close() {
// 资源清理（如有）
}
}⚠️ 注意：authenticate() 中务必调用 context.success()（成功）或 context.failure(...)（失败），否则流程将挂起；避免抛出未捕获异常，Keycloak 会将其转为 500 错误。
✅ 2. 提供工厂类（AuthenticatorFactory）
CustomAuthenticatorFactory 负责向 Keycloak SPI 框架声明该认证器的存在、元信息与生命周期管理：
public class CustomAuthenticatorFactory implements AuthenticatorFactory {
public static final String PROVIDER_ID = "custom-sso";
private static final CustomAuthenticator SINGLETON = new CustomAuthenticator();
@Override
public String getDisplayType() {
return "Custom SSO Authenticator"; // 后台管理界面显示名称
}
@Override
public String getReferenceCategory() {
return "custom"; // 分组标识（非必需，但建议设置）
}
@Override
public boolean isConfigurable() {
return false; // 若无需后台配置项（如密钥输入框），返回 false
}
@Override
public AuthenticationExecutionModel.Requirement[] getRequirementChoices() {
return new AuthenticationExecutionModel.Requirement[]{
AuthenticationExecutionModel.Requirement.REQUIRED,
AuthenticationExecutionModel.Requirement.ALTERNATIVE,
AuthenticationExecutionModel.Requirement.DISABLED
};
}
@Override
public Authenticator create(KeycloakSession session) {
return SINGLETON;
}
@Override
public String getId() {
return PROVIDER_ID;
}
@Override
public String getHelpText() {
return "Authenticates users via custom fields (fieldA, fieldB, hash).";
}
}✅ 3. 完成 SPI 注册（关键！）
在项目资源目录下创建文件：
src/main/resources/META-INF/services/org.keycloak.authentication.AuthenticatorFactory
内容仅一行（指向你的工厂类全限定名）：
前后端完整代码包括本馆动态，新书来了，书籍榜单，服务指南，进馆预约，活动讲座预约等功能，采用腾讯提供的小程序云开发解决方案，无须服务器和域名 预约管理：开始/截止时间/人数均可灵活设置，可以自定义客户预约填写的数据项 预约凭证：支持线下到场后校验签到/核销/二维码自助签到等多种方式详尽的 预约数据：支持预约名单数据导出Excel，打印
com.example.auth.CustomAuthenticatorFactory
? 必须确保该文件路径和类名完全准确，且构建后存在于 JAR/WAR 的 META-INF/services/ 下。Maven 构建时需确认资源被正确打包。
✅ 4. 打包并部署到 Keycloak
- 将模块编译为 JAR（推荐使用 Maven Shade Plugin 或普通 mvn package）；
- 将 JAR 放入 Keycloak 的 providers/ 目录（如 keycloak-22.0.5/standalone/deployments/ 或 providers/）；
- 重启 Keycloak（或热部署，取决于版本）；
- 登录 Admin Console → Realm Settings → Authentication → Flows。
✅ 5. 绑定到认证流（不可修改内置流！）
- 点击 Browser Flow 右侧复制按钮（?），命名为 browser-custom；
- 进入新流程，点击右上角 + Execution → 选择你的 Custom SSO Authenticator；
- 拖动至合适位置（通常放在 Username Password Form 之前或替代它）；
- 将 Browser Flow 的下拉框切换为刚创建的 browser-custom；
- ✅ 保存。
? 提示：若需支持 /token 端点（即密码模式 grant_type=password），你必须将此 Authenticator 绑定到 Direct Grant Flow（而非 Browser Flow）。同理，分别配置 Direct Grant Flow 的副本并插入你的执行器。
✅ 6. 测试端点（Direct Grant 示例）
curl -X POST \ 'http://localhost:8080/realms/myrealm/protocol/openid-connect/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'client_id=myclient' \ -d 'grant_type=password' \ -d 'fieldA=13800138000' \ -d 'fieldB=ABC123' \ -d 'hash=7f8c4e...a9b2'
Keycloak 将调用你的 CustomAuthenticator.authenticate()，完成校验并返回标准 access_token 响应。
? 总结与最佳实践
- ✅ 永远复制内置流程再修改：Browser、Direct Grant 等均为只读模板，直接编辑会失败；
- ✅ 参数获取方式统一：Keycloak 在 AuthenticationFlowContext 中自动解析 x-www-form-urlencoded 和部分 JSON 请求体，无需手动读取 raw body；
- ✅ 安全强化建议：在 isValid() 中加入时间恒定比较（MessageDigest.isEqual）、防重放（timestamp + nonce）、IP 限流等；
- ✅ 日志与可观测性：使用 context.getEvent().detail(...) 记录审计字段，便于排查；
- ❌ 避免阻塞操作：远程 HTTP 调用请使用异步非阻塞方式（如 KeycloakSession.asyncInvocation()），防止线程池耗尽。
完成以上步骤，你便拥有了一个生产就绪的 Keycloak 自定义认证流程——灵活、可维护、与原生体验无缝融合。
