Envoy GCP 认证过滤器新增 token_metadata_key将 GCP 认证令牌写入动态元数据【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy导读Envoy 的 GCP 认证过滤器envoy.filters.http.gcp_authn负责从 GCE Metadata Server 获取 GCP 认证令牌并注入到请求中。当前开发版本见 changelogs/current/new_features/gcp_authn__token-metadata-key.rst新增了token_metadata_key配置字段不再局限于把令牌写入 HTTP 请求头而是可以将令牌保存到以过滤器配置名为命名空间的**动态元数据dynamic metadata**中供过滤器链中的下游过滤器、路由动作或上层控制面消费。阅读完本文你将掌握该字段的配置方法、优先级语义、底层源码实现以及如何在iam_access_token等依赖动态元数据的场景中利用这一新能力。一、特性背景GCP 认证过滤器的令牌注入方式GCP 认证过滤器用于服务到服务service-to-service认证场景。当多个私有服务需要互相通信时Envoy 作为代理在请求转发前从 GCE Metadata Server 获取认证令牌identity token / access token并把它注入到发往目标服务的请求中避免请求因缺少凭据而被目标服务拒绝。其整体行为在 GCP Authentication Filter 文档 中有完整描述。在引入token_metadata_key之前令牌的注入位置完全由请求头决定共有两种方式对应 proto 中token_header字段与默认行为默认行为写入Authorization请求头格式为Authorization: Bearer token自定义请求头通过token_header.name指定头名、token_header.value_prefix指定前缀格式为value_prefixtoken例如Bearer带一个尾随空格此时令牌写入自定义头。上述逻辑完整体现在过滤器实现 gcp_authn_filter.cc 的addTokenToRequest方法中第 253-270 行这也是token_metadata_key特性落地的位置。二、token_metadata_key 配置项详解token_metadata_key定义在过滤器配置 proto 中见 gcp_authn.proto第 52-54 行// Optional dynamic metadata key to save the token. The metadata uses the filter config name as the namespace. // Takes precedence over token_header. string token_metadata_key 7;关键语义如下要点说明字段类型string可选字段配置过滤器配置名空间下的动态元数据键名命名空间以**过滤器配置名filter config name**作为动态元数据命名空间即envoy.filters.http.gcp_authn优先级一旦设置token_header不再生效未设置时回退到token_header/ 默认Authorization: Bearer token数据形态令牌以字符串值写入动态元数据的 Struct 字段中从 proto 注释可以确认该字段位于GcpAuthnFilterConfig的第 7 号字段当前结构[#next-free-field: 9]与token_header字段 4、cluster字段 5、timeout字段 6、audience字段 8并列。与 token_header 的优先级关系配置字段之间遵循明确的优先级token_metadata_keytoken_header 默认Authorization头。proto 中token_header字段第 46-50 行的注释也印证了这一点默认情况下未指定该字段令牌写入Authorization头格式为Authorization: Bearer token。若设置了token_metadata_key该字段不生效。三、完整配置示例官方配置示例文件 gcp-authn-filter-configuration.yaml 给出了过滤器与集群的完整配置。在 HTTP 过滤器链中启用该过滤器并配置token_metadata_key的写法如下static_resources: listeners: - address: socket_address: address: 0.0.0.0 port_value: 8000 filter_chains: - filters: - name: http typed_config: type: type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager codec_type: HTTP2 stat_prefix: config_test route_config: name: route_config_0 virtual_hosts: - name: integration domains: [*] routes: - match: prefix: / route: cluster: cluster_0 http_filters: - name: envoy.filters.http.gcp_authn typed_config: type: type.googleapis.com/envoy.extensions.filters.http.gcp_authn.v3.GcpAuthnFilterConfig http_uri: uri: http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience[AUDIENCE] cluster: gcp_authn timeout: 10s # 新增将获取到的令牌保存到动态元数据中 # 命名空间为 envoy.filters.http.gcp_authn键名为 token token_metadata_key: token - name: envoy.filters.http.router typed_config: type: type.googleapis.com/envoy.extensions.filters.http.router.v3.Router clusters: - name: cluster_0 # Cluster for fake destination service which has typed metadata that contains the audience information. load_assignment: cluster_name: cluster_0 endpoints: - lb_endpoints: - endpoint: address: socket_address: address: 0.0.0.0 port_value: 8000 typed_extension_protocol_options: envoy.extensions.upstreams.http.v3.HttpProtocolOptions: type: type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions explicit_http_config: http2_protocol_options: {} metadata: typed_filter_metadata: envoy.filters.http.gcp_authn: type: type.googleapis.com/envoy.extensions.filters.http.gcp_authn.v3.Audience url: http://test.com # Cluster for GCE metadata server - name: gcp_authn type: STRICT_DNS connect_timeout: 5s dns_lookup_family: V4_ONLY load_assignment: cluster_name: gcp_authn endpoints: - lb_endpoints: - endpoint: address: socket_address: address: metadata.google.internal port_value: 80需要注意http_uri字段在 proto 中已被标记为 deprecated计划在 3.0 版本废弃控制面应优先使用新增的cluster与timeout字段来配置元数据服务器访问http_uri仅作向后兼容兜底见 gcp_authn.proto 第 28-37 行。四、源码级实现原理1. 核心写入逻辑addTokenToRequesttoken_metadata_key的实现位于 gcp_authn_filter.cc 的GcpAuthnFilter::addTokenToRequest第 253-270 行void GcpAuthnFilter::addTokenToRequest(Http::RequestHeaderMap hdrs, absl::string_view token_str) { const FilterConfigProto proto filter_config_-config(); if (!proto.token_metadata_key().empty()) { Protobuf::Struct metadata; (*metadata.mutable_fields())[proto.token_metadata_key()].set_string_value(token_str); decoder_callbacks_-streamInfo().setDynamicMetadata( std::string(decoder_callbacks_-filterConfigName()), metadata); return; } const envoy::extensions::filters::http::gcp_authn::v3::TokenHeader header proto.token_header(); if (header.ByteSizeLong() 0) { std::string id_token absl::StrCat(Bearer , token_str); hdrs.setCopy(authorizationHeaderKey(), id_token); } else { std::string id_token absl::StrCat(header.value_prefix(), token_str); hdrs.setCopy(Http::LowerCaseString(header.name()), id_token); } }实现要点分支优先级在代码层面固化只要token_metadata_key非空函数立即构造Protobuf::Struct并将令牌以字符串值放入metadata[token_metadata_key]随后调用streamInfo().setDynamicMetadata(filterConfigName(), metadata)写入动态元数据并return完全跳过请求头写入逻辑命名空间取自过滤器配置名decoder_callbacks_-filterConfigName()返回的是配置中该过滤器的名字如envoy.filters.http.gcp_authn这正是 proto 注释所述以过滤器配置名为命名空间的由来令牌原文写入写入动态元数据的是令牌原始字符串JWT 或 access token不带Bearer前缀。2. 调用链addTokenToRequest在两条路径上被调用见 gcp_authn_filter.cc缓存命中路径decodeHeaders中先查TokenCache命中时直接调用addTokenToRequest(hdrs, token.value())后Continue第 188-196 行不发起对元数据服务器的异步请求异步获取完成路径onComplete回调中在continueDecoding()之前调用addTokenToRequest将令牌写入第 223-244 行。因此无论令牌来自缓存还是新获取写入动态元数据的路径是统一的。五、下游如何消费动态元数据中的令牌写入动态元数据后过滤器链中排在gcp_authn之后的过滤器、路由动作等都可以按filter_metadata[envoy.filters.http.gcp_authn][token]的形态读取该令牌。仓库内一个典型的下游消费场景是iam_access_token见 gcp_authn__iam-access-token.rst 与 gcp_authn.proto 第 88-100 行它的authorization字段是 substitution formatter 模板官方注释给出的示例为Bearer %DYNAMIC_METADATA(gcp_authn:token)%也就是说先由 gcp_authn 过滤器用token_metadata_key把 GCE 令牌写入gcp_authn命名空间再通过%DYNAMIC_METADATA(gcp_authn:token)%模板在 IAM 令牌请求中复用它作为授权头底层格式化逻辑见 gcp_authn_filter.cc 第 72-82 行构造的account_formatter_/auth_formatter_。这从仓库证据上说明了token_metadata_key的实际价值让令牌不落入 HTTP 请求头而是在请求处理管道内部以结构化方式流转供其他基于动态元数据的组件复用。六、测试验证仓库测试 gcp_authn_filter_test.cc 为token_metadata_key提供了三组针对性用例可作为行为契约测试用例验证内容SaveTokenToDynamicMetadata第 993 行配置token_metadata_key: custom_token_key后令牌以该键写入setDynamicMetadata(envoy.filters.http.gcp_authn, ...)且Authorization头保持为空SaveTokenToDynamicMetadataCacheHit第 1025 行缓存命中时同样走动态元数据写入路径缓存令牌值为cached_token不触发异步客户端调用TokenMetadataKeyPrecedenceOverTokenHeader第 1060 行同时配置token_metadata_key与token_header时token_metadata_key优先自定义请求头custom-header与Authorization均未被写入测试代码还展示了预期的元数据结构expected_metadata.fields[custom_token_key]为字符串值第 1006-1010 行与实现中Protobuf::Struct的写入方式一一对应。测试中的过滤器配置名 mock 为envoy.filters.http.gcp_authn第 999-1000 行印证了命名空间语义。七、使用注意事项结合 proto 注释与实现使用token_metadata_key时有几点需要留意优先级的明确性设置该字段后令牌不再出现在任何请求头中。若下游依赖Authorization头透传令牌需评估是否受影响命名空间一致性写入位置是streamInfo的动态元数据命名空间为过滤器配置名。消费方读取时必须使用相同的命名空间与键名例如%DYNAMIC_METADATA(gcp_authn:token)%数据形态动态元数据中保存的是令牌原文无Bearer前缀消费方若需要组装标准认证头需自行添加前缀适用范围token_metadata_key与token_header、audience、cache_config等字段一样proto 注释标注并非所有 data plane 都支持跨实现使用时需确认目标 data plane 的能力见 gcp_authn.proto 相关字段注释当前状态该字段属于changelogs/current中的新特性即当前开发分支引入的能力适用于使用最新版本代码构建的 Envoy。总结token_metadata_key是 gcp_authn 过滤器令牌传递方式的补充通道它以过滤器配置名为命名空间将获取到的 GCP 认证令牌写入动态元数据优先级高于token_header与默认Authorization头。从 proto 定义 到 过滤器实现 再到 单元测试该特性的语义清晰、行为有测试保障为基于动态元数据令牌流转的复杂认证编排如iam_access_token的 substitution formatter 消费提供了基础能力。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考