本文详细讲解如何在 keycloak 中实现基于自定义字段（如 fielda、fieldb、hash）的 oauth 2.0 密码模式认证流程，替代默认的 username/password 验证，并完成 authenticator 与 authenticatorfactory 的注册、部署及流程绑定。
要在 Keycloak 中实现完全自定义的认证逻辑（例如接收 fieldA、fieldB 和 hash 作为凭证，而非标准 username/password），并使其兼容标准 OIDC Token 端点（如 POST /realms/{realm}/protocol/openid-connect/token?grant_type=password），仅实现 Authenticator 接口是不够的——你必须将其封装为可插拔的 SPI（Service Provider Interface）组件，并通过 Keycloak 管理控制台启用。以下是完整、可落地的操作流程：
✅ 第一步：实现核心认证逻辑（Authenticator）
你的 CustomAuthenticator 需从请求中提取自定义参数，并完成业务校验（如签名验证、令牌解密、第三方系统鉴权等）。注意：Keycloak 默认密码流要求用户已存在且处于启用状态，因此需确保 UserModel 被正确关联。
public class CustomAuthenticator implements Authenticator {
@Override
public void authenticate(AuthenticationFlowContext context) {
// 1. 从表单请求中获取自定义字段（非 username/password）
String fieldA = context.getHttpRequest().getDecodedFormParameters().getFirst("fieldA");
String fieldB = context.getHttpRequest().getDecodedFormParameters().getFirst("fieldB");
String hash = context.getHttpRequest().getDecodedFormParameters().getFirst("hash");
// 2. 执行自定义校验逻辑（示例：简单哈希比对，生产环境请使用 HMAC/签名验签）
if (isValidCredentials(fieldA, fieldB, hash)) {
// 3. 根据 fieldA（或其它唯一标识）查找对应用户（注意：需确保该用户已在 Keycloak 中存在）
UserModel user = context.getSession()
.users()
.getUserByUsername(fieldA, context.getRealm()); // 或用 getUserById / searchUsersByAttribute
if (user != null && user.isEnabled()) {
context.setUser(user);
context.success(); // 认证成功 → 进入后续步骤（如角色映射、token 发放）
return;
}
}
// 认证失败：返回标准错误响应
context.failure(AuthenticationFlowError.INVALID_USER);
}
private boolean isValidCredentials(String fieldA, String fieldB, String hash) {
// ✅ 替换为实际业务逻辑：如调用内部服务、验证 JWT、校验 HMAC-SHA256 签名等
return "expected-hash".equals(hash) && fieldA != null && fieldB != null;
}
@Override
public void action(AuthenticationFlowContext context) {
// 此方法用于处理表单提交后的 POST 操作（如二次确认），纯 API 流程中通常无需实现
authenticate(context);
}
@Override
public boolean requiresUser() {
return true; // 表明此步骤需要关联一个用户（否则 context.setUser() 无效）
}
@Override
public boolean configuredFor(KeycloakSession session, RealmModel realm, UserModel user) {
return true; // 简化处理；如需细粒度控制（如仅对某类用户启用），可在此校验
}
@Override
public void setRequiredActions(KeycloakSession session, RealmModel realm, UserModel user) {
// 可选：设置强制操作（如首次登录修改密码）
}
@Override
public void close() {
// 资源清理（如关闭连接池），若无则留空
}
}⚠️ 关键注意事项：authenticate() 中必须调用 context.setUser(user) + context.success()，否则 Keycloak 不会颁发 token；用户必须预先存在于 Realm 中（可通过 Admin REST API、管理控制台或用户联合方式导入），Keycloak 不支持“动态创建用户+认证”一体化（除非额外实现 UserStorageProvider）；若需无用户预置的场景（如手机号+短信验证码直登），应结合 UserStorageProvider 或改用 Direct Grant 流程扩展。
✅ 第二步：提供工厂类（AuthenticatorFactory）
AuthenticatorFactory 是 Keycloak 加载你认证器的入口，负责声明元信息并返回实例：
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 Flow"; // 控制台中显示的名称
}
@Override
public String getReferenceCategory() {
return "custom-auth"; // 分组标识（可选）
}
@Override
public boolean isConfigurable() {
return false; // 如无需运行时配置，设为 false
}
@Override
public AuthenticationExecutionModel.Requirement[] getRequirementChoices() {
return new AuthenticationExecutionModel.Requirement[]{
AuthenticationExecutionModel.Requirement.REQUIRED,
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 fieldA/fieldB/hash credentials.";
}
}✅ 第三步：注册 SPI 服务
在项目资源目录下创建文件：
src/main/resources/META-INF/services/org.keycloak.authentication.AuthenticatorFactory
Word报告自动生成神器。自动生成专业Word文档报告，支持模板填充、目录生成、表格/图表插入、页眉页脚、多级标题、样式主题、批量邮件合并。当用户需要生成Word报告、创建合同文档、批量生成通知/证书、填充Word模板、制作商业计划书时触发。
文件内容仅一行（指向你的 Factory 实现类）：
com.example.auth.CustomAuthenticatorFactory
? 提示：确保构建后该文件存在于 JAR 包的 META-INF/services/ 路径下。
✅ 第四步：打包部署与流程绑定
- 将模块打包为 JAR（推荐使用 Maven Shade Plugin 合并依赖）；
- 将 JAR 放入 Keycloak 的 providers/ 目录（如 $KEYCLOAK_HOME/providers/）；
- 重启 Keycloak（或执行 bin/kc.sh build --features=preview + kc.sh start，取决于版本）；
- 登录管理控制台 → Realm Settings → Authentication → Flows；
- 复制内置 Direct Grant 流程（因 Browser 流不支持密码模式，而 Direct Grant 才是 /token?grant_type=password 的实际载体）；
- 在新流程中，点击 + Execution → 选择你的 Custom SSO Flow → 设为 REQUIRED；
- 返回 Authentication → Bindings，将 Direct Grant Flow 绑定到你新建的自定义流程。
✅ 最终验证（cURL 示例）
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 "client_secret=xxx" \ -d "grant_type=password" \ -d "fieldA=user123" \ -d "fieldB=serviceX" \ -d "hash=abc123def456"
✅ 成功时将返回标准 OIDC token 响应（含 access_token, refresh_token, expires_in）。
? 总结
- Keycloak 自定义认证 ≠ 仅写一个 Authenticator，而是完整的 SPI 插件开发流程；
- 必须配套 AuthenticatorFactory + META-INF/services 注册 + 控制台流程绑定；
- Direct Grant 流程是密码模式的载体，不可修改内置 Browser 流；
- 用户必须预先存在，认证器只负责“验证身份”，不负责“创建身份”；
- 生产环境务必强化安全校验（防重放、签名时效、密钥轮转、审计日志）。
遵循以上步骤，即可安全、稳定地将 Keycloak 集成至任意自有认证体系，实现真正的协议兼容与业务解耦。
