oauth2-proxy 7.1.x Alpha 配置详解YAML 结构化配置、参数参考与旧配置迁移方法【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxyoauth2-proxy 的 Alpha 配置是官方为替代传统 TOML 配置文件与命令行标志flags而设计的 YAML 结构化配置方案以AlphaOptions为根节点覆盖上游服务器、请求/响应头注入与 HTTP(S) 服务监听等核心维度。本篇基于 7.1.x 版本文档完整梳理其结构、默认值与全部字段语义并结合仓库源码说明--alpha-config的加载流程、--convert-config-to-alpha的迁移机制以及启用后不可再用的旧选项清单帮助你在生产环境中安全地规划与执行配置迁移。一、Alpha 配置是什么为什么要引入警告本页对应的是 alpha早期功能。oauth2-proxy 保留随时对 alpha 功能做破坏性变更的权利且不做任何预告。这些选项可能被修改、移除、重命名或移动使用 alpha 配置项前务必知晓此风险。传统配置方式依赖 TOML 文件--config加大量扁平化命令行标志配置项彼此松散、难以表达列表型结构多个上游、多个注入头。Alpha 配置则按语义分组采用 YAML 描述AlphaOptions作为整个配置的根节点形如upstreams: - id: ... ... injectRequestHeaders: - name: ... ... injectResponseHeaders: - name: ... ...在 main.go 中可以确认这三个配置入口的定义config : configFlagSet.String(config, , path to config file) alphaConfig : configFlagSet.String(alpha-config, , path to alpha config file (use at your own risk - the structure in this config file may change between minor releases)) convertConfig : configFlagSet.Bool(convert-config-to-alpha, false, if true, the proxy will load configuration as normal and convert existing configuration to the alpha config structure, and print it to stdout)从源码结构看alpha 配置是叠加层而非替代层loadConfiguration先加载 legacy 配置若指定了--alpha-config则再调用loadYamlOptions将 YAML 反序列化到AlphaOptions最后通过MergeOptionsWithDefaults覆盖回核心Options结构体见 main.go 与 pkg/apis/options/alpha_options.go。也就是说认证提供者、Cookie 会话等尚未迁移的部分仍可继续写在传统--config文件中这正是文档中新旧配置可同时提供的运行方式。启动时程序还会打印一条明确的警告日志提醒使用者结构可能随时变化WARNING: You are using alpha configuration. The structure in this configuration file may change without notice. You MUST remove conflicting options from your existing configuration.二、如何使用 Alpha 配置按 Configuration Reference 中描述的结构生成 YAML 文件然后使用--alpha-config标志提供其路径即可。注意启用--alpha-config后一部分旧选项不再可用必须先从既有配置中删除详见下文移除的选项一节。将旧配置转换为新的结构在正式启用--alpha-config之前先用convert-config-to-alpha标志把现有配置转换到新格式oauth2-proxy --convert-config-to-alpha --config ./path/to/existing/config.cfg该命令会加载全部被新格式支持的选项转换为 YAML 并输出到STDOUT。将其复制到一个新文件、删除下文列出的不可用选项后用新配置启动oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg源码层面的实现链路很直接main检测到--convert-config-to-alpha后调用printConvertedConfig先用options.NewAlphaOptions(opts)从已加载的核心选项中抽取字段ExtractFrom再经options.Decode转成通用 map 并用yaml.Marshal打印到标准输出见 main.go。另外程序明确禁止--alpha-config与--convert-config-to-alpha、--config-test与--convert-config-to-alpha同时使用违反会直接logger.Fatal退出。三、移除的选项启用 alpha 配置后不可再用以下标志/选项及其对应环境变量在使用 alpha 配置时不再可用来自 Legacy Upstream FlagSet上游相关标志环境变量flush-intervalflush_intervalpass-host-headerpass_host_headerproxy-websocketsproxy_websocketsssl-upstream-insecure-skip-verifyssl_upstream_insecure_skip_verifyupstreamupstreams来自 Legacy Headers FlagSet头部注入相关标志环境变量pass-basic-authpass_basic_authpass-access-tokenpass_access_tokenpass-user-headerspass_user_headerspass-authorization-headerpass_authorization_headerset-basic-authset_basic_authset-xauthrequestset_xauthrequestset-authorization-headerset_authorization_headerprefer-email-to-userprefer_email_to_userbasic-auth-passwordbasic_auth_passwordskip-auth-strip-headersskip_auth_strip_headers当--alpha-config已设置时若仍通过标志或配置文件使用上述选项会导致错误。这些上游/头部标志在新格式中分别由upstreams列表与injectRequestHeaders/injectResponseHeaders取代如flush-interval对应每个上游的flushIntervalpass-user-headers的语义对应claimSource注入头。旧标志的注册位置可参考 pkg/apis/options/legacy_options.go 中的FlushInterval/PassHostHeader/Upstreams字段定义。重要在使用--alpha-config启动前必须删除这些选项。四、配置参考Configuration Reference以下参考以AlphaOptions为根。AlphaOptionsAlphaOptions承载 alpha 结构化配置选项用于访问主配置结构中尚不可用的 alpha 功能。其字段如下字段类型说明upstreamsUpstreams配置上游服务器。用户认证后代理会根据该列表定义的路径映射把请求转发到这些上游。injectRequestHeaders[]Header配置需添加到发往上游请求中的头部。头部值可取自已认证用户的会话也可取静态密钥值。injectResponseHeaders[]Header配置需添加到代理响应中的头部。典型场景是 oauth2-proxy 作为外部认证提供方配合 NGINX 的auth_request模块等另一层代理使用。值来源同上。serverServer配置代理应用的 HTTP(S) 服务器。可同时运行 HTTP 与 HTTPS 服务器需同时设置BindAddress与SecureBindAddress启用安全服务器必须配置 TLS 证书与私钥。metricsServerServer配置 metrics 的 HTTP(S) 服务器语义同server。Upstreams 与 UpstreamUpstreams是[]Upstream的别名即上游服务器定义的集合。Upstream表示一个上游服务器路径匹配时请求即被代理到它字段类型说明与默认值idstring上游的唯一标识符所有上游必填。pathstring用于将请求映射到上游服务器。最接近最长匹配优先所有path必须唯一。uristring上游服务器的 URI可为 HTTP(S) 服务或file://文件 URL可携带路径前缀。例如http://localhost:8080、https://service.localhost、https://service.localhost/path、file://host/path。若 URI 路径为/base入站请求为/dir则转发到上游时路径为/base/dir。insecureSkipTLSVerifybool跳过对上游 HTTPS 主机的 TLS 校验。不安全可能招致中间人攻击。默认false。staticbool使发往该上游的所有请求返回静态响应响应体为Authenticated响应码取staticCode未设置时返回 200。staticCodeint静态响应的响应码仅可与static一起使用。默认 200。flushIntervalDuration流式传输上游响应时刷新响应缓冲的周期。默认 1 秒。passHostHeaderbool是否将请求的 Host 头透传给上游服务器。默认true。proxyWebSocketsbool是否启用到上游的 WebSocket 代理。默认true。默认值在 pkg/apis/options/upstreams.go 中以常量集中声明DefaultUpstreamFlushInterval 1s、DefaultUpstreamTimeout 30s、DefaultUpstreamPassHostHeader true 等并在EnsureDefaults中逐项补齐指针零值。一个值得注意的实现细节当static: true时EnsureDefaults会强制覆盖用户设置将uri清空、passHostHeader与proxyWebSockets置为false以保证静态上游行为一致见 upstreams.go 中 Force defaults compatible with static upstreams 注释段。从当前主分支源码结构看Upstream后续版本还扩展了rewriteTarget基于path捕获组的正则路径重写、timeout默认 30 秒、disableKeepAlives等字段且上游集合被收纳到upstreamConfig节点下含全局proxyRawPath开关字段语义与本文一致可参考 pkg/apis/options/upstreams.go 了解演进方向。HeaderHeader表示一个将添加到请求或响应中的头部字段类型说明namestring头部名称同一列表内应唯一。preserveRequestValuebool是否保留客户端请求中该头部的原有值仅对注入的请求头有效。默认false匹配到的同名头部会被剥离。values[]HeaderValue该头部期望的值列表。HeaderValueHeaderValue表示单个头部值及其可能的取值来源字段类型说明value[]byte期望 base64 编码的字符串值对应 SecretSource。fromEnvstring期望一个环境变量名。fromFilestring期望一个包含密钥值的文件路径。claimstring期望从会话中读取的 claim 名称对应 ClaimSource。prefixstring非空时作为前缀拼接到 claim 值前面。basicAuthPasswordSecretSource将该 claim 转换为 Basic Auth 头claim 值作为用户名basicAuthPassword作为密码。从源码结构看HeaderValue实际由内嵌的*SecretSource与*ClaimSource两个子结构组合而成YAML 中即写作嵌套的secretSource/claimSource键见 pkg/apis/options/header.go。此外 header.go 的注释列出了可直接使用的会话 claim 名称access_token、id_token、created_at、expires_on、refresh_token、email、user、groups、preferred_username可作为claim字段取值的参考集合。ClaimSourceClaimSource用于从会话中的 claim 加载头部值字段类型说明claimstring要从会话中读取值的 claim 名称。prefixstring非空时前置拼接到 claim 值前。basicAuthPasswordSecretSource把该 claim 转换为 Basic Auth 头claim 值为用户名basicAuthPassword为密码。SecretSourceSecretSource引用一个单独的密钥值同一时间只能定义其中一个来源出现于ClaimSource、HeaderValue、TLS中字段类型说明value[]byte期望 base64 编码的字符串值。fromEnvstring期望一个环境变量名。fromFilestring期望一个包含密钥值的文件路径。对应实现见 pkg/apis/options/secret_source.go三个字段互斥、优先级由加载逻辑保证。DurationDuration是字符串别名的时间表示出现于Upstream.flushInterval一个可带符号的十进制数字序列每段可带可选小数与单位后缀如300ms、-1.5h、2h45m。合法时间单位ns、us或µs、ms、s、m、h。ServerServer表示一个 HTTP(S) 服务器的配置字段类型说明bindAddressstring提供流量的监听地址。留空或设为-表示禁用。secureBindAddressstring提供安全流量的监听地址。留空或设为-表示禁用。tlsTLS加载安全流量证书与私钥所需的信息。从源码结构看Server.BindAddress支持多种地址形式[http://]addr:port、fd:intsystemd socket 场景、unix://pathUnix socketIPv6 需加方括号如http://[::1]:4180SecureBindAddress对应https://形式见 pkg/apis/options/server.go这些写法在 7.1.x 时代同样适用于server/metricsServer字段。TLSTLS包含加载 TLS 证书与私钥的信息字段类型说明keySecretSourceTLS 私钥数据通常来自文件。certSecretSourceTLS 证书数据通常来自文件。当前主分支的 server.go 中还扩展了minVersion最低 TLS 版本如TLS1.3与cipherSuites允许的加密套件列表缺省使用 Go 默认安全套件迁移时可一并评估。五、完整配置示例仓库内置的本地联调样例仓库contrib/local-environment目录下提供了一个可直接运行的 alpha 配置实例 oauth2-proxy-alpha-config.yaml配套 docker-compose 环境见 contrib/local-environment/README.md是很好的参照server: bindAddress: 0.0.0.0:4180 upstreamConfig: upstreams: - id: httpbin path: / uri: http://httpbin injectRequestHeaders: - name: X-Forwarded-User values: - claimSource: claim: user - name: X-Forwarded-Email values: - claimSource: claim: email providers: - id: oidc provider: oidc clientSecret: b2F1dGgyLXByb3h5LWNsaWVudC1zZWNyZXQK clientID: oauth2-proxy oidcConfig: issuerURL: http://dex.localtest.me:5556/dex逐段解读server.bindAddress: 0.0.0.0:4180代理监听 4180 端口oauth2-proxy 默认端口未设置secureBindAddress即不启用 HTTPS。上游定义id: httpbin、path: /所有路径最长前缀匹配到该上游请求转发至http://httpbin服务。两个注入请求头均使用claimSourceX-Forwarded-User取会话 claimuserX-Forwarded-Email取email让上游应用无需解密会话即可获知当前用户——这正是injectRequestHeaders替代旧pass-user-headers标志的方式。clientSecret是一个 base64 字符串解码后为示例环境的明文秘钥演示了SecretSource.value的 base64 用法生产环境建议改用fromEnv/fromFile。该样例主分支形态还展示了providers块与upstreamConfig嵌套结构即 7.1.x 文档中根级upstreams列表在后续版本中的演进形态。迁移完成后可用oauth2-proxy --config-test --config ./config.cfg --alpha-config ./config.yaml之类的组合先做校验--config-test会执行validation.Validate后打印 configuration is valid 并退出见 main.go再正式启用--alpha-config启动。六、关键源码索引内容路径--alpha-config/--convert-config-to-alpha入口与加载合并逻辑main.goAlphaOptions结构体与新旧结构互转pkg/apis/options/alpha_options.go上游字段、默认值常量与静态上游强制覆盖逻辑pkg/apis/options/upstreams.goHeader/HeaderValue/ClaimSource及可用 claim 列表pkg/apis/options/header.goSecretSource三选一来源pkg/apis/options/secret_source.goServer/TLS结构与地址格式说明pkg/apis/options/server.go被移除的 legacy 上游/头部标志定义pkg/apis/options/legacy_options.go可运行的 alpha 配置样例contrib/local-environment/oauth2-proxy-alpha-config.yaml【免费下载链接】oauth2-proxyA reverse proxy that provides authentication with Google, Azure, OpenID Connect and many more identity providers.项目地址: https://gitcode.com/GitHub_Trending/oa/oauth2-proxy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考