如何告知OAuth2 API客户端缺少凭证？Vert.x REST API认证最佳实践

我刚好处理过类似的场景——REST API和传统Web应用的OAuth2处理逻辑确实不一样，重定向登录页完全不符合API无状态、客户端自主处理的设计原则。下面是针对这个需求的最佳实践和具体实现步骤：

核心思路 #

REST API要严格遵循HTTP语义，未认证请求直接返回401 Unauthorized，同时通过WWW-Authenticate响应头告知客户端需要使用Bearer令牌，让客户端自行发起令牌获取流程（比如调用Keycloak的token端点，根据业务场景选择授权码、密码或客户端凭证授权）。

具体实现步骤 #

1. 配置Keycloak客户端适配API场景 #

首先在Keycloak控制台修改你的客户端配置：

• 找到对应客户端，将Access Type设置为bearer-only
• 保存配置后，Keycloak会跳过重定向登录逻辑，直接对无效/缺失令牌返回401

这个配置从认证服务器层面关闭了重定向行为，是适配API场景的关键一步。

2. 自定义Vert.x OAuth2Handler的未认证响应 #

即使Keycloak配置正确，默认的Vert.x OAuth2Handler可能仍保留重定向逻辑，需要我们自定义denyHandler来返回标准的401响应：

// 1. 初始化Keycloak配置（可从json文件读取或硬编码）
JsonObject keycloakConfig = new JsonObject()
    .put("realm", "your-realm-name")
    .put("public-key", "your-keycloak-public-key")
    .put("auth-server-url", "http://your-keycloak-url/auth")
    .put("resource", "your-client-id")
    .put("credentials", new JsonObject().put("secret", "your-client-secret"));

// 2. 创建OAuth2Auth provider，使用BEARER_ONLY流程
OAuth2Auth oauth2 = OAuth2Auth.create(vertx, OAuth2FlowType.BEARER_ONLY, keycloakConfig);

// 3. 创建OAuth2Handler并自定义未认证处理逻辑
OAuth2Handler oauth2Handler = OAuth2Handler.create(oauth2);

// 自定义拒绝访问的响应，返回标准401和提示信息
oauth2Handler.denyHandler(ctx -> {
    ctx.response()
        .setStatusCode(401)
        // 符合HTTP标准的WWW-Authenticate头，明确告知客户端需要Bearer令牌
        .putHeader("WWW-Authenticate", "Bearer realm=\"your-realm-name\", error=\"invalid_token\"")
        .putHeader("Content-Type", "application/json")
        .end(new JsonObject()
            .put("error", "unauthorized")
            .put("message", "Valid Bearer token is required to access this resource")
            .encode());
});

// 4. 将handler应用到所有受保护的API路由
router.route("/api/**").handler(oauth2Handler);

3. 客户端侧的配套处理 #

当客户端收到401响应时，应该：

• 解析WWW-Authenticate头的提示信息
• 根据业务授权方式（比如密码授权、客户端凭证授权），调用Keycloak的/auth/realms/{realm}/protocol/openid-connect/token端点获取令牌
• 后续请求在Authorization头中携带Bearer {token}

额外注意事项 #

• 如果你的API需要支持用户登录（比如授权码授权），不要设置bearer-only，保留confidential或public的Access Type，但必须关闭Vert.x的自动重定向：

  OAuth2Handler handler = OAuth2Handler.create(oauth2, "http://your-callback-url");
  // 关闭自动重定向逻辑
  handler.setRedirectURI(null);
  // 依然使用自定义denyHandler返回401
  

• Vert.x的OAuth2Handler会自动验证令牌的签名、有效期和受众，无需手动处理这些细节
• 可以添加令牌刷新逻辑：客户端收到401且WWW-Authenticate头包含error="invalid_token"时，尝试用刷新令牌获取新的访问令牌

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