自定义Keycloak 22登录流程：用户校验与自动创建需求咨询

完全可以通过Keycloak的Authenticator SPI实现你需求的登录逻辑，这是Keycloak官方提供的扩展登录流程的标准方式，以下是具体实现步骤：

一、开发自定义认证器 #

1. 依赖配置 #

首先在Maven/Gradle项目中引入Keycloak核心SPI依赖（版本需与你的Keycloak实例一致）：

<dependencies>
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-core</artifactId>
        <version>22.0.5</version> <!-- 替换为你的Keycloak版本 -->
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-server-spi</artifactId>
        <version>22.0.5</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-server-spi-private</artifactId>
        <version>22.0.5</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

2. 核心逻辑实现 #

创建自定义认证器类，实现Authenticator和AuthenticatorFactory接口，核心逻辑在authenticate方法中：

public class ExternalApiAuthenticator implements Authenticator {

    @Override
    public void authenticate(AuthenticationFlowContext context) {
        // 获取用户提交的用户名和密码
        UsernamePasswordCredentials credentials = (UsernamePasswordCredentials) context.getCredentials();
        String username = credentials.getUsername();
        String password = credentials.getPassword();
        RealmModel realm = context.getRealm();
        KeycloakSession session = context.getSession();

        // 1. 检查用户是否已存在
        UserModel existingUser = session.users().getUserByUsername(username, realm);
        if (existingUser != null) {
            // 用户存在，直接通过认证，走原有流程
            context.success();
            return;
        }

        // 2. 用户不存在，调用外部API校验凭证
        boolean isExternalValid = callExternalAuthApi(username, password);
        if (!isExternalValid) {
            // 外部验证失败，触发凭证错误，走原有失败流程
            context.failure(AuthenticationError.INVALID_CREDENTIALS);
            return;
        }

        // 3. 外部验证通过，创建新用户
        UserModel newUser = session.users().addUser(realm, username);
        newUser.setEnabled(true);
        // 设置用户密码（Keycloak会自动加密存储）
        session.userCredentialManager().updateCredential(realm, newUser, UserCredentialModel.password(password));
        // 添加自定义属性（根据外部API返回结果设置）
        newUser.setSingleAttribute("external_auth_source", "third-party-api");
        // 可添加更多属性，如邮箱、手机号等

        // 认证成功，进入后续流程
        context.success();
    }

    // 封装外部API调用逻辑，需自行实现HTTP请求
    private boolean callExternalAuthApi(String username, String password) {
        // 示例：使用HttpURLConnection发送POST请求到外部API
        // 注意：务必使用HTTPS传输，避免密码泄露
        try {
            URL url = new URL("https://your-external-api.com/auth");
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setDoOutput(true);

            String jsonInputString = "{\"username\":\"" + username + "\",\"password\":\"" + password + "\"}";
            try(OutputStream os = conn.getOutputStream()) {
                byte[] input = jsonInputString.getBytes("utf-8");
                os.write(input, 0, input.length);
            }

            int responseCode = conn.getResponseCode();
            return responseCode == HttpURLConnection.HTTP_OK;
        } catch (Exception e) {
            // API调用异常时，默认返回验证失败，或根据需求降级处理
            return false;
        }
    }

    // 其他接口方法（如action、requiresUser等）按需实现，此处省略
    // ...

    // 实现AuthenticatorFactory接口，用于注册认证器
    public static class Factory implements AuthenticatorFactory {
        @Override
        public String getId() {
            return "external-api-authenticator"; // 认证器唯一ID，配置时会用到
        }

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

        // 其他工厂方法按需实现，此处省略
        // ...
    }
}

3. 打包部署 #

将项目打包为JAR文件，放置到Keycloak安装目录的providers文件夹下，然后执行以下命令重新构建并重启Keycloak：

# Linux/macOS
./kc.sh build
./kc.sh start

# Windows
kc.bat build
kc.bat start

二、配置Keycloak登录流程 #

1. 登录Keycloak管理控制台，进入目标Realm，选择Authentication -> Flows
2. 点击Browser流程右侧的Actions，选择Copy，命名为Custom Browser Flow（避免修改默认流程）
3. 展开Custom Browser Flow下的Forms节点，点击Username Password Form右侧的Actions，选择Add Execution
4. 在下拉列表中选择你开发的external-api-authenticator（对应工厂类的getId()值），设置为REQUIRED
5. 调整执行顺序：确保external-api-authenticator在Username Password Form之后（先收集用户凭证，再执行自定义逻辑）
6. 将Realm的默认登录流程切换为Custom Browser Flow：进入Authentication -> Bindings，在Browser Flow下拉列表中选择Custom Browser Flow

三、关键注意事项 #

• 外部API可靠性：添加超时、重试机制，避免因外部API故障导致登录阻塞；可设置降级逻辑（如API不可用时直接走原有登录流程）
• 安全防护：外部API调用必须使用HTTPS，禁止明文传输密码；创建用户时，Keycloak会自动加密存储密码，无需手动处理
• 权限控制：确保Keycloak有足够权限创建用户（默认Realm管理员权限即可），集群环境需在所有节点部署插件
• 测试覆盖：验证三种核心场景：已存在用户登录、新用户外部验证通过自动创建、新用户外部验证失败

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