Keycloak 21.1自定义REST端点404问题排查求助

问题背景 #

在Keycloak 21.1中实现自定义REST端点：

• 编写了HashRegistrationEndpointFactory和HashRegistrationEndpoint代码
• 配置了META-INF/org.keycloak.services.resource.RealmResourceProviderFactory文件
• 将构建后的jar放入Keycloak的providers目录
• 执行kc.bat build和kc.bat start-dev启动服务器，服务器运行正常
• 访问端点URL http://localhost:8080/auth/realms/realm_name/custom-registration-endpoint/hash-register?hash=a&issuer=b&email=c&ruc=d&isValidId=e 时返回404

一、URL路径错误排查 #

Keycloak 17+版本已移除默认的/auth上下文前缀，这是导致404最常见的原因：

• 正确的基础URL应为 http://localhost:8080/realms/realm_name/，无需附加/auth
• 调整后的完整请求URL：http://localhost:8080/realms/realm_name/custom-registration-endpoint/hash-register?hash=a&issuer=b&email=c&ruc=d&isValidId=e

额外确认：

• realm_name需与Keycloak中实际存在的领域名称完全一致（区分大小写）
• URL中的custom-registration-endpoint需与工厂类定义的资源ID完全匹配

二、配置与代码遗漏排查 #

1. 资源工厂配置文件检查 #

确保META-INF/org.keycloak.services.resource.RealmResourceProviderFactory文件内容正确：

• 文件仅包含一行，为工厂类的全限定名，例如：com.yourpackage.HashRegistrationEndpointFactory
• 检查包名、类名的拼写和大小写是否完全匹配代码

2. 工厂类ID定义检查 #

确认HashRegistrationEndpointFactory的getId()方法返回值与URL中的资源前缀一致：

@Override
public String getId() {
    return "custom-registration-endpoint"; // 必须和URL中的前缀完全匹配
}

3. 端点类JAX-RS注解检查 #

确保HashRegistrationEndpoint的注解配置符合要求：

• 类上需添加@Path("")或@Path("/")（基础路径已由工厂类提供）
• 方法上的@Path需为hash-register，且HTTP方法注解（@GET/@POST等）与请求方式匹配：

@Path("")
public class HashRegistrationEndpoint implements RealmResourceProvider {
    @GET
    @Path("hash-register")
    public Response handleHashRegister(
        @QueryParam("hash") String hash,
        @QueryParam("issuer") String issuer,
        @QueryParam("email") String email,
        @QueryParam("ruc") String ruc,
        @QueryParam("isValidId") String isValidId
    ) {
        // 业务逻辑实现
        return Response.ok().build();
    }

    // 实现RealmResourceProvider的close方法
    @Override
    public void close() {}
}

4. 部署构建流程检查 #

• 确认jar包已正确放入providers目录，文件无损坏
• 执行kc.bat build时，查看启动日志，确认Keycloak已加载你的自定义提供者（搜索工厂类名）
• Windows环境下检查文件权限，确保Keycloak可读取该jar包

5. API兼容性检查 #

确认代码继承/实现了正确的Keycloak接口：

• 工厂类需继承org.keycloak.services.resource.RealmResourceProviderFactory
• 端点类需实现org.keycloak.services.resource.RealmResourceProvider

三、调试建议 #

• 查看Keycloak日志文件（logs/keycloak.log），搜索是否有自定义提供者加载失败的错误信息
• 使用kc.bat start-dev --log-level debug启动服务器，获取更详细的资源注册日志，定位问题

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