Keycloak 19：限制Gmail账号使用用户名密码登录并保留账号锁功能

核心思路 #

通过自定义认证器拦截用户名密码登录流程，针对性处理Gmail账号与非Gmail账号的认证逻辑，同时配合Keycloak国际化配置实现多语言提示。

1. 编写自定义认证器 #

创建实现Authenticator接口的Java类，拦截认证流程并做分支处理：

• 识别Gmail账号（以@gmail.com结尾），直接返回认证失败并跳过锁定逻辑
• 放行非Gmail账号，保留原生账号锁定功能

核心代码示例 #

public class GmailBlockAuthenticator implements Authenticator {

    @Override
    public void authenticate(AuthenticationFlowContext context) {
        UsernamePasswordCredential credential = (UsernamePasswordCredential) context.getCredential();
        String username = credential.getUsername();
        
        // 判断是否为Gmail账号
        if (username != null && username.toLowerCase().endsWith("@gmail.com")) {
            // 抛出多语言错误提示，对应消息键需在国际化配置中添加
            Response challenge = context.form()
                .setError("gmail-required-broker-login")
                .createErrorPage(Response.Status.UNAUTHORIZED);
            context.failure(AuthenticationFlowError.INVALID_CREDENTIALS, challenge);
            // 标记失败原因，跳过账号失败次数累加
            context.getEvent().detail(Details.FAILURE_REASON, "Gmail account requires broker login");
            return;
        }
        
        // 非Gmail账号，放行至原生认证逻辑
        context.success();
    }

    @Override
    public void action(AuthenticationFlowContext context) {
        authenticate(context);
    }

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

    @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() {
    }
}

2. 打包部署认证器 #

• 依赖Keycloak 19的keycloak-core和keycloak-server-spi包，将代码打包为JAR
• 将JAR放入Keycloak的providers目录（如/opt/keycloak/providers）
• 执行./kc.sh build（Windows环境用kc.bat build）重新构建Keycloak

3. 修改认证流程 #

在目标Realm中配置自定义认证器的执行顺序：

1. 进入Authentication -> Flows，复制默认的Browser流程，命名为Browser-with-Gmail-Block
2. 在复制后的流程中，找到Username Password Form步骤，点击Add Execution
3. 选择自定义认证器（如gmail-block-authenticator），设置Requirement为REQUIRED，并将其移动到Username Password Form之前
4. 将该流程设为Realm的默认浏览器认证流程

4. 配置多语言错误提示 #

1. 进入Realm Settings -> Internationalization，按需添加需要支持的语言
2. 点击对应语言的Edit按钮，添加消息键值对：
   • 英文：gmail-required-broker-login=Please use Gmail identity broker to log in.
   • 中文：gmail-required-broker-login=请使用Gmail身份代理登录。
3. 保存配置

5. 验证效果 #

• 输入Gmail账号+任意密码：直接显示对应语言的错误提示，账号不会被锁定
• 输入非Gmail账号+错误密码：正常累加失败次数，达到阈值后触发账号锁定
• 输入非Gmail账号+正确密码：正常完成登录

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