如何强制Keycloak转发x-request-id请求头以实现链路追踪？

问题场景 #

在Ambassador API网关管理的Kubernetes集群中，使用Keycloak实现OAuth2授权码流程，同时通过Istio服务网格提供可观测性与mTLS功能。Jaeger链路追踪要求所有服务转发x-request-id请求头以关联完整链路，但目前存在以下问题：
请求发送时，Ambassador的Istio代理生成x-request-id并转发至Keycloak授权，但Keycloak返回结果至Ambassador时该请求头被丢弃，导致Keycloak的Istio代理生成新的x-request-id，链路追踪断裂。

关联的Keycloak环境变量ConfigMap配置如下：

kind: ConfigMap
apiVersion: v1
metadata:
  name: keycloak-envars
data:
  KEYCLOAK_ADMIN: "admin"
  KC_PROXY: "edge"
  KC_DB: "postgres"
  KC_DB_USERNAME: "test"
  KC_DB_DATABASE: "keycloak"
  PROXY_ADDRESS_FORWARDING: "true"

解决方案 #

方法1：通过Keycloak环境变量配置强制转发请求头 #

针对Keycloak 17+版本，可通过环境变量指定需要转发的请求头。修改ConfigMap，添加以下配置：

KC_HTTP_FORWARD_HEADERS: "x-request-id"

或者使用SPI配置更精细的头部控制：

KC_SPI_HTTP_FORWARD_HEADERS_INCLUDE: "x-request-id"

更新ConfigMap后重启Keycloak Pod，Keycloak会自动在响应中携带传入的x-request-id头部。

方法2：利用Istio VirtualService强制保留响应头 #

通过Istio的VirtualService配置，在Keycloak的响应路径上强制设置x-request-id头部，直接复用请求中的值。创建如下VirtualService资源：

apiVersion: networking.istio.io/v1alpha3
kind: VirtualService
metadata:
  name: keycloak-vs
  namespace: <your-keycloak-namespace>
spec:
  hosts:
  - keycloak.<your-keycloak-namespace>.svc.cluster.local
  http:
  - route:
    - destination:
        host: keycloak.<your-keycloak-namespace>.svc.cluster.local
        port:
          number: 8080
    headers:
      response:
        set:
          x-request-id: "%REQ(x-request-id)%"

该配置会在Keycloak返回响应时，将请求中的x-request-id值直接设置到响应头中，确保链路追踪的连续性。

方法3：检查Istio Sidecar配置确保头部不被过滤 #

确认Istio的Sidecar配置没有过滤x-request-id头部。可以在Keycloak的Pod上添加以下Annotation，确保Sidecar正确处理该头部：

metadata:
  annotations:
    sidecar.istio.io/inject: "true"
    traffic.sidecar.istio.io/includeInboundPorts: "8080"
    traffic.sidecar.istio.io/includeOutboundPorts: "*"

同时，也可以在Istio的MeshConfig中全局配置默认保留x-request-id：

apiVersion: install.istio.io/v1alpha1
kind: IstioOperator
spec:
  meshConfig:
    defaultConfig:
      proxyMetadata:
        ISTIO_META_REQUEST_ID_HEADER: "x-request-id"
      headers:
        response:
          set:
            x-request-id: "%REQ(x-request-id)%"

方法4：自定义Keycloak过滤器强制携带响应头 #

如果上述方法无效，可以编写一个简单的Servlet过滤器，让Keycloak在响应中自动添加x-request-id头部：

1. 创建一个Java类实现javax.servlet.Filter接口，在doFilter方法中从请求获取x-request-id并设置到响应头：

public class RequestIdFilter implements Filter {
    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
        HttpServletRequest req = (HttpServletRequest) request;
        HttpServletResponse res = (HttpServletResponse) response;
        String requestId = req.getHeader("x-request-id");
        if (requestId != null) {
            res.setHeader("x-request-id", requestId);
        }
        chain.doFilter(request, response);
    }
}

2. 将过滤器打包成JAR，部署到Keycloak的providers目录，并在standalone.xml中注册该过滤器：

<filters>
    <filter name="requestIdFilter" class="com.yourpackage.RequestIdFilter"/>
</filters>
<filter-mappings>
    <filter-mapping name="requestIdFilter" url-pattern="/*"/>
</filter-mappings>

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