如何配置Keycloak实现注册时强制验证用户同意勾选？

针对你在Keycloak 3.4.3.Final自定义注册主题中遇到的「未勾选同意复选框仍能注册」的问题，我们可以通过自定义服务端FormAction验证的方式解决，完全符合你不使用JavaScript、不依赖内置Terms and Conditions方案的要求。下面是详细步骤：

1. 编写自定义FormAction验证类 #

我们需要创建一个服务端验证组件，在注册流程提交时检查同意复选框的状态，未勾选则阻止注册并返回错误。

步骤1：创建Maven项目并添加依赖 #

创建一个普通Java Maven项目，在pom.xml中添加Keycloak核心依赖（版本需与你的3.4.3.Final匹配）：

<dependencies>
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-core</artifactId>
        <version>3.4.3.Final</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-server-spi</artifactId>
        <version>3.4.3.Final</version>
        <scope>provided</scope>
    </dependency>
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-server-spi-private</artifactId>
        <version>3.4.3.Final</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

步骤2：实现FormAction接口 #

创建一个Java类，实现Keycloak的FormAction接口，核心逻辑在validate方法中检查复选框参数：

package com.yourcompany.keycloak.actions;

import org.keycloak.authentication.FormAction;
import org.keycloak.authentication.FormContext;
import org.keycloak.authentication.ValidationContext;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.models.UserModel;

import javax.ws.rs.core.MultivaluedMap;
import java.util.List;

public class RegistrationConsentValidator implements FormAction {

    @Override
    public void buildPage(FormContext formContext, MultivaluedMap<String, String> formData) {
        // 无需构建页面，我们已在自定义主题中添加了复选框
    }

    @Override
    public void validate(ValidationContext validationContext) {
        MultivaluedMap<String, String> formData = validationContext.getHttpRequest().getDecodedFormParameters();
        List<String> consentValue = formData.get("user.attributes.registration_consent1");
        
        // 检查复选框是否被勾选：只有当参数存在且值为"on"时才通过验证
        if (consentValue == null || consentValue.isEmpty() || !"on".equals(consentValue.get(0))) {
            // 添加自定义错误标识，用于前端展示
            validationContext.error("registration-consent-required");
            validationContext.validationError(formData, "missing-required-field");
            return;
        }
        
        // 验证通过，继续注册流程
        validationContext.success();
    }

    @Override
    public void success(FormContext formContext) {
        // 无需额外处理，Keycloak会自动保存用户属性
    }

    @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() {
        // 资源清理（无特殊需求可留空）
    }
}

步骤3：注册FormAction实现 #

在项目的src/main/resources/META-INF/services目录下创建文件org.keycloak.authentication.FormAction，内容为你的类全路径：

com.yourcompany.keycloak.actions.RegistrationConsentValidator

步骤4：打包部署 #

将项目打包成JAR文件，复制到Keycloak服务器的standalone/deployments目录下，Keycloak会自动检测并部署该组件。

2. 配置Keycloak注册流程 #

部署完成后，需要将自定义验证器添加到注册流程中：

1. 登录Keycloak后台，进入目标Realm，点击Authentication -> Flows
2. 找到默认的Registration流程，点击右侧的Copy，命名为Custom Registration Flow（自定义名称）
3. 展开新创建的流程下的Registration Forms，点击Add execution
4. 在弹出的列表中找到你的RegistrationConsentValidator（若未显示，重启Keycloak重试），添加后设置Requirement为REQUIRED
5. 将该验证器拖动到User Creation步骤之前（确保创建用户前先验证同意状态）
6. 进入Authentication -> Bindings，将Registration Flow设置为你刚才创建的Custom Registration Flow

3. 自定义主题中添加错误提示 #

在你的自定义注册主题的register.ftl模板中，为复选框添加错误信息展示：

<div class="form-group">
    <input type="checkbox" name="user.attributes.registration_consent1" id="consent_checkbox" />
    <label for="consent_checkbox">我同意相关服务条款</label>
    <!-- 显示自定义错误信息 -->
    <#if messages.existsError('registration-consent-required')>
        <span class="error-message">${msg('registration-consent-required')}</span>
    </#if>
</div>

同时在主题的messages.properties文件中添加对应的错误文案：

registration-consent-required=请勾选同意服务条款

效果验证 #

现在用户未勾选同意复选框提交注册时，Keycloak会触发服务端验证，返回错误信息并阻止注册流程，页面上会显示你定义的错误提示，完全满足需求。

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