Postman请求Keycloak认证的Spring微服务返回HTML登录页是什么原因

问题根因 #

你的配置本身没有问题，也不是Postman Bug，出现该现象的核心原因是你当前API网关使用的Authorization Code授权码流是面向浏览器端交互场景的授权模式：

• 浏览器访问时你已经完成了Keycloak登录流程，浏览器存储了有效会话Cookie，请求时自动携带Cookie，网关识别到已授权身份因此正常返回结果
• Postman直接发送请求时没有完成授权流程，也没有携带有效身份凭证（有效Cookie/Access Token），因此被Spring Security重定向到Keycloak登录页，返回HTML格式的登录内容

解决方案 #

方案1：在Postman中直接走授权码流获取令牌（推荐，和浏览器访问逻辑一致）

Postman内置了完整的OAuth2授权流程支持，无需手动复制Cookie，按以下步骤配置即可：

1. 打开你要发送的请求，切换到Authorization标签，Type选择OAuth 2.0
2. 在页面下方Configure New Token区域填写以下配置：
   • Grant Type：选择Authorization Code
   • Callback URL：可直接使用Postman默认值，注意要将该地址提前添加到Keycloak对应客户端的「有效重定向URI」列表中
   • Auth URL：填写http://localhost:2727/auth/realms/demo-microservice-realm/protocol/openid-connect/auth
   • Access Token URL：填写http://localhost:2727/auth/realms/demo-microservice-realm/protocol/openid-connect/token
   • Client ID：填写demo-cloud-gateway-client
   • Client Secret：填写39ea2ef6-90a7-47ca-9892-fda60127f47e
3. 点击「Get New Access Token」按钮，在弹出的Keycloak登录页输入账号密码完成登录，Postman会自动获取到有效令牌
4. 点击「Use Token」，Postman会自动将令牌添加到请求头Authorization字段中，此时发送GET/POST请求都能正常得到响应

方案2：网关新增资源服务器配置，支持直接传递令牌

如果你需要支持服务间调用、无需用户交互的场景，可以给API网关添加资源服务器能力，直接校验请求头携带的JWT令牌：

1. 修改API网关的配置文件，新增资源服务器配置：

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: http://localhost:2727/auth/realms/demo-microservice-realm/protocol/openid-connect/certs

2. 调整网关的Spring Security配置类，同时支持OAuth2登录和JWT令牌校验，核心配置参考：

@Bean
public SecurityFilterChain securityFilterChain(ServerHttpSecurity http) throws Exception {
    http
        .authorizeExchange(exchanges -> exchanges.anyExchange().authenticated())
        .oauth2Login(Customizer.withDefaults())
        .oauth2ResourceServer(ServerHttpSecurity.OAuth2ResourceServerSpec::jwt);
    return http.build();
}

配置完成后，你可以直接从Keycloak获取令牌，放在请求头Authorization: Bearer <令牌内容>中发送请求即可，无需走登录流程，该方式更适合接口测试、服务间调用场景。

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