如何用Keycloak保障OpenTelemetry Collector Gateway的OTLP/HTTP端点安全

核心认知纠正 #

OTLP/HTTP是机器对机器的API端点，并非面向浏览器的Web应用，因此不会自动跳转到Keycloak登录页面。返回UNAUTHORISED的原因是请求未携带合法的Keycloak访问令牌，或配置存在错误。

排查与解决步骤 #

1. 验证OpenTelemetry Collector的OIDC认证配置 #

确保Collector正确配置了OIDC扩展和OTLP端点的认证规则：

• 启用oidc扩展，并配置Keycloak的issuer地址、匹配的audience：

  extensions:
    oidc:
      issuer_url: "https://<keycloak-domain>/auth/realms/<your-realm>"
      audience: "<keycloak-client-id>" # 需与Keycloak客户端的audience一致
  receivers:
    otlp:
      protocols:
        http:
          auth:
            authenticator: oidc # 指定使用oidc认证器
  service:
    extensions: [oidc] # 必须在service中启用oidc扩展
    pipelines:
      traces:
        receivers: [otlp]
        # 其余pipeline配置...
  

• 检查Collector日志，确认OIDC扩展是否成功加载，是否能正常连接Keycloak获取JWKS密钥。

2. 检查Keycloak客户端配置 #

• Access Type：根据使用场景设置：
  • 机器对机器的服务调用（如SDK直接上报）：设为confidential，并记录客户端密钥；
  • 无密钥的客户端（如浏览器端SDK）：设为public。
• Audience配置：确保客户端的Audience（或Keycloak Realm的Default Audience）与Collector配置中的audience完全一致。
• 授权流开启：根据认证方式开启对应流：
  • 客户端凭证流：开启Service Accounts Enabled；
  • 授权码流：确保Valid Redirect URIs配置正确（若需用户交互获取令牌）。

3. 确保请求正确携带访问令牌 #

OTLP/HTTP请求必须通过Authorization请求头携带Bearer令牌：

• 用curl测试的示例命令（客户端凭证流）：

  # 先从Keycloak获取令牌
  ACCESS_TOKEN=$(curl -s -X POST https://<keycloak-domain>/auth/realms/<your-realm>/protocol/openid-connect/token \
    -d "grant_type=client_credentials" \
    -d "client_id=<your-client-id>" \
    -d "client_secret=<your-client-secret>" | jq -r '.access_token')
  
  # 携带令牌上报遥测数据
  curl -X POST https://<otel-gateway>:4318/v1/traces \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d @trace-payload.json
  

• 若使用OpenTelemetry SDK，需配置OTLP Exporter的请求头，例如Java SDK：

  OtlpHttpSpanExporter exporter = OtlpHttpSpanExporter.builder()
      .setEndpoint("https://<otel-gateway>:4318/v1/traces")
      .addHeader("Authorization", "Bearer " + accessToken)
      .build();
  

4. 验证令牌有效性 #

使用Keycloak的令牌 introspect 端点检查令牌是否合法：

curl -X POST https://<keycloak-domain>/auth/realms/<your-realm>/protocol/openid-connect/token/introspect \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<your-access-token>" \
  -d "client_id=<your-client-id>" \
  -d "client_secret=<your-client-secret>"

检查返回结果：

• active字段必须为true；
• aud字段需包含Collector配置的audience；
• exp字段需未超出过期时间。

关于"跳转登录页"的补充说明 #

如果需要通过用户交互（浏览器登录Keycloak）获取令牌后再访问OTLP端点，OTel Collector本身不支持此功能，需在Collector前添加反向代理（如Nginx、Traefik），由代理层处理Keycloak的OAuth2授权码流，获取令牌后再转发请求到OTLP端点。

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