From 34c2712c99f0aef23240a276e9f7f6775269689f Mon Sep 17 00:00:00 2001 From: Jan Larwig Date: Thu, 15 Jan 2026 11:46:19 +0100 Subject: [PATCH] doc: add changelog and migration guide for v7.14.0 alpha config changes Signed-off-by: Jan Larwig --- CHANGELOG.md | 47 +++++++++- docs/docs/configuration/alpha_config.md | 91 +++++++++++++++++-- docs/docs/configuration/alpha_config.md.tmpl | 91 +++++++++++++++++-- .../configuration/alpha_config.md | 91 +++++++++++++++++-- .../configuration/alpha_config.md.tmpl | 91 +++++++++++++++++-- 5 files changed, 386 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b604c15..332d1560 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,18 +12,63 @@ ## Release Highlights +- 🕵️‍♀️ Vulnerabilities have been addressed + - [CVE-2025-61729](https://access.redhat.com/security/cve/cve-2025-61729) + - [CVE-2025-61727](https://access.redhat.com/security/cve/cve-2025-61727) + - [CVE-2025-47914](https://access.redhat.com/security/cve/cve-2025-47914) + - [CVE-2025-58181](https://access.redhat.com/security/cve/cve-2025-58181) +- 🗂️ Alpha Config YAML parsing revamped using mapstructure with custom decoders +- 🐛 Squashed some bugs + ## Important Notes +This release introduces a breaking change for Alpha Config users and moves us significantly +closer to removing legacy configuration parameters, making the codebase of OAuth2 Proxy more +future proof and extensible. + +From v7.14.0 onward, header injection sources must be explicitly nested. If you +previously relied on squashed fields, update to the new structure before upgrading: + +```yaml +# before v7.14.0 +injectRequestHeaders: +- name: X-Forwarded-User + values: + - claim: user +- name: X-Custom-Secret-header + values: + - value: my-super-secret + +# v7.14.0 and later +injectRequestHeaders: +- name: X-Forwarded-User + values: + - claimSource: + claim: user +- name: X-Custom-Secret-header + values: + - secretSource: + value: my-super-secret +``` + +We are committed to Semantic Versioning and usually avoid breaking changes without a major version release. +Advancing Alpha Config toward its Beta stage required this exception, and even for the Alpha Config we try +to keep breaking changes in v7 to a minium. Thank you for understanding the need for this step to prepare +the project for future maintainability and future improvements like structured logging. + ## Breaking Changes +- Alpha Config: header injection no longer supports squashed claim/secret sources; they must now be set explicitly (see example above). + ## Changes since v7.13.0 -- [#3290](https://github.com/oauth2-proxy/oauth2-proxy/pull/3290) fix: WebSocket proxy to respect PassHostHeader setting (@UnsignedLong) +- [#2628](https://github.com/oauth2-proxy/oauth2-proxy/pull/2628) feat(structured config): revamp of yaml parsing using mapstructure decoder and custom decoders (@tuunit) - [#3197](https://github.com/oauth2-proxy/oauth2-proxy/pull/3197) fix: NewRemoteKeySet is not using DefaultHTTPClient (@rsrdesarrollo / @tuunit) - [#3292](https://github.com/oauth2-proxy/oauth2-proxy/pull/3292) chore(deps): upgrade gomod and bump to golang v1.25.5 (@tuunit) - [#3304](https://github.com/oauth2-proxy/oauth2-proxy/pull/3304) fix: added conditional so default is not always set and env vars are honored fixes 3303 (@pixeldrew) - [#3264](https://github.com/oauth2-proxy/oauth2-proxy/pull/3264) fix: more aggressively truncate logged access_token (@MartinNowak / @tuunit) - [#3267](https://github.com/oauth2-proxy/oauth2-proxy/pull/3267) fix: Session refresh handling in OIDC provider (@gysel) +- [#3290](https://github.com/oauth2-proxy/oauth2-proxy/pull/3290) fix: WebSocket proxy to respect PassHostHeader setting (@UnsignedLong) # V7.13.0 diff --git a/docs/docs/configuration/alpha_config.md b/docs/docs/configuration/alpha_config.md index 495bc206..b4a75582 100644 --- a/docs/docs/configuration/alpha_config.md +++ b/docs/docs/configuration/alpha_config.md @@ -24,17 +24,56 @@ When using alpha configuration, your config file will look something like below: upstreams: - id: ... ...: ... +providers: + - id: ... + ...: ... +cookie: + secret: ... + ...: ... injectRequestHeaders: - - name: ... - ...: ... + - secretSource: + ...: ... injectResponseHeaders: - - name: ... - ...: ... + - claimSource: + ...: ... ``` Please browse the [reference](#configuration-reference) below for the structure of the new configuration format. +# Migration Guide + +This section details breaking changes and migration steps for moving to the new +alpha configuration format. + +## Migrating header injections in v7.14.0 + +From v7.14.0 onward, header injection sources must be explicitly nested. If you +previously relied on squashed fields, update to the new structure before +upgrading: + +```yaml +# before v7.14.0 +injectRequestHeaders: +- name: X-Forwarded-User + values: + - claim: user +- name: X-Custom-Secret-header + values: + - value: my-super-secret + +# v7.14.0 and later +injectRequestHeaders: +- name: X-Forwarded-User + values: + - claimSource: + claim: user +- name: X-Custom-Secret-header + values: + - secretSource: + value: my-super-secret +``` + ## Using Alpha Configuration To use the new **alpha** configuration, generate a YAML file based on the format @@ -67,9 +106,9 @@ the new config. oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg ``` -## Using ENV variables in the alpha configuration +### How to use environment variables -The alpha package supports the use of environment variables in place of yaml keys, allowing sensitive values to be pulled from somewhere other than the yaml file. +The alpha package supports the use of environment variables in place of yaml values, allowing sensitive data to be pulled from somewhere other than the yaml file. When using environment variables, your yaml will look like this: ```yaml @@ -81,6 +120,46 @@ When using environment variables, your yaml will look like this: Where CLIENT_SECRET is an environment variable. More information and available patterns can be found [here](https://github.com/a8m/envsubst#docs) +### How to inject custom headers + +Configure `injectRequestHeaders` and `injectResponseHeaders` in alpha config YAML. + +```yaml +injectRequestHeaders: + - name: "X-User-Email" + values: + - claimSource: + claim: "email" # extract the email claim contents from the id token + - name: "X-Static-Secret" + values: + # secrets need to be encoded with base64 when directly in the yaml config but will be send decoded + - secretSource: + value: "c3VwZXItc2VjcmV0" + - name: "X-Static-File-Secret" + - secretSource: + fromFile: "/path/to/my/secret" + - name: "X-Static-Env-Secret" + - secretSource: + value: "${MY_SECRET_ENV}" # content still needs to be base64 encoded +injectResponseHeaders: + # Following will result in a header "Authorization: Basic (encoded)" + - name: "Authorization" + values: + - claimSource: + claim: user + prefix: "Basic " + basicAuthPassword: + value: c3VwZXItc2VjcmV0LXBhc3N3b3Jk # base64 encoded password +``` + +**Value sources:** +* `claimSource` - `claim` (session claims either from id token or from profile URL) +* `secretSource` - `value` (base64), `fromFile` (file path) + +**Request option:** `preserveRequestValue: true` retains existing header values + +**Incompatibility:** Remove legacy flags `pass-user-headers`, `set-xauthrequest` + ## Removed options The following flags/options and their respective environment variables are no diff --git a/docs/docs/configuration/alpha_config.md.tmpl b/docs/docs/configuration/alpha_config.md.tmpl index 8258201f..081657c4 100644 --- a/docs/docs/configuration/alpha_config.md.tmpl +++ b/docs/docs/configuration/alpha_config.md.tmpl @@ -24,17 +24,56 @@ When using alpha configuration, your config file will look something like below: upstreams: - id: ... ...: ... +providers: + - id: ... + ...: ... +cookie: + secret: ... + ...: ... injectRequestHeaders: - - name: ... - ...: ... + - secretSource: + ...: ... injectResponseHeaders: - - name: ... - ...: ... + - claimSource: + ...: ... ``` Please browse the [reference](#configuration-reference) below for the structure of the new configuration format. +# Migration Guide + +This section details breaking changes and migration steps for moving to the new +alpha configuration format. + +## Migrating header injections in v7.14.0 + +From v7.14.0 onward, header injection sources must be explicitly nested. If you +previously relied on squashed fields, update to the new structure before +upgrading: + +```yaml +# before v7.14.0 +injectRequestHeaders: +- name: X-Forwarded-User + values: + - claim: user +- name: X-Custom-Secret-header + values: + - value: my-super-secret + +# v7.14.0 and later +injectRequestHeaders: +- name: X-Forwarded-User + values: + - claimSource: + claim: user +- name: X-Custom-Secret-header + values: + - secretSource: + value: my-super-secret +``` + ## Using Alpha Configuration To use the new **alpha** configuration, generate a YAML file based on the format @@ -67,9 +106,9 @@ the new config. oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg ``` -## Using ENV variables in the alpha configuration +### How to use environment variables -The alpha package supports the use of environment variables in place of yaml keys, allowing sensitive values to be pulled from somewhere other than the yaml file. +The alpha package supports the use of environment variables in place of yaml values, allowing sensitive data to be pulled from somewhere other than the yaml file. When using environment variables, your yaml will look like this: ```yaml @@ -81,6 +120,46 @@ When using environment variables, your yaml will look like this: Where CLIENT_SECRET is an environment variable. More information and available patterns can be found [here](https://github.com/a8m/envsubst#docs) +### How to inject custom headers + +Configure `injectRequestHeaders` and `injectResponseHeaders` in alpha config YAML. + +```yaml +injectRequestHeaders: + - name: "X-User-Email" + values: + - claimSource: + claim: "email" # extract the email claim contents from the id token + - name: "X-Static-Secret" + values: + # secrets need to be encoded with base64 when directly in the yaml config but will be send decoded + - secretSource: + value: "c3VwZXItc2VjcmV0" + - name: "X-Static-File-Secret" + - secretSource: + fromFile: "/path/to/my/secret" + - name: "X-Static-Env-Secret" + - secretSource: + value: "${MY_SECRET_ENV}" # content still needs to be base64 encoded +injectResponseHeaders: + # Following will result in a header "Authorization: Basic (encoded)" + - name: "Authorization" + values: + - claimSource: + claim: user + prefix: "Basic " + basicAuthPassword: + value: c3VwZXItc2VjcmV0LXBhc3N3b3Jk # base64 encoded password +``` + +**Value sources:** +* `claimSource` - `claim` (session claims either from id token or from profile URL) +* `secretSource` - `value` (base64), `fromFile` (file path) + +**Request option:** `preserveRequestValue: true` retains existing header values + +**Incompatibility:** Remove legacy flags `pass-user-headers`, `set-xauthrequest` + ## Removed options The following flags/options and their respective environment variables are no diff --git a/docs/versioned_docs/version-7.14.x/configuration/alpha_config.md b/docs/versioned_docs/version-7.14.x/configuration/alpha_config.md index 495bc206..b4a75582 100644 --- a/docs/versioned_docs/version-7.14.x/configuration/alpha_config.md +++ b/docs/versioned_docs/version-7.14.x/configuration/alpha_config.md @@ -24,17 +24,56 @@ When using alpha configuration, your config file will look something like below: upstreams: - id: ... ...: ... +providers: + - id: ... + ...: ... +cookie: + secret: ... + ...: ... injectRequestHeaders: - - name: ... - ...: ... + - secretSource: + ...: ... injectResponseHeaders: - - name: ... - ...: ... + - claimSource: + ...: ... ``` Please browse the [reference](#configuration-reference) below for the structure of the new configuration format. +# Migration Guide + +This section details breaking changes and migration steps for moving to the new +alpha configuration format. + +## Migrating header injections in v7.14.0 + +From v7.14.0 onward, header injection sources must be explicitly nested. If you +previously relied on squashed fields, update to the new structure before +upgrading: + +```yaml +# before v7.14.0 +injectRequestHeaders: +- name: X-Forwarded-User + values: + - claim: user +- name: X-Custom-Secret-header + values: + - value: my-super-secret + +# v7.14.0 and later +injectRequestHeaders: +- name: X-Forwarded-User + values: + - claimSource: + claim: user +- name: X-Custom-Secret-header + values: + - secretSource: + value: my-super-secret +``` + ## Using Alpha Configuration To use the new **alpha** configuration, generate a YAML file based on the format @@ -67,9 +106,9 @@ the new config. oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg ``` -## Using ENV variables in the alpha configuration +### How to use environment variables -The alpha package supports the use of environment variables in place of yaml keys, allowing sensitive values to be pulled from somewhere other than the yaml file. +The alpha package supports the use of environment variables in place of yaml values, allowing sensitive data to be pulled from somewhere other than the yaml file. When using environment variables, your yaml will look like this: ```yaml @@ -81,6 +120,46 @@ When using environment variables, your yaml will look like this: Where CLIENT_SECRET is an environment variable. More information and available patterns can be found [here](https://github.com/a8m/envsubst#docs) +### How to inject custom headers + +Configure `injectRequestHeaders` and `injectResponseHeaders` in alpha config YAML. + +```yaml +injectRequestHeaders: + - name: "X-User-Email" + values: + - claimSource: + claim: "email" # extract the email claim contents from the id token + - name: "X-Static-Secret" + values: + # secrets need to be encoded with base64 when directly in the yaml config but will be send decoded + - secretSource: + value: "c3VwZXItc2VjcmV0" + - name: "X-Static-File-Secret" + - secretSource: + fromFile: "/path/to/my/secret" + - name: "X-Static-Env-Secret" + - secretSource: + value: "${MY_SECRET_ENV}" # content still needs to be base64 encoded +injectResponseHeaders: + # Following will result in a header "Authorization: Basic (encoded)" + - name: "Authorization" + values: + - claimSource: + claim: user + prefix: "Basic " + basicAuthPassword: + value: c3VwZXItc2VjcmV0LXBhc3N3b3Jk # base64 encoded password +``` + +**Value sources:** +* `claimSource` - `claim` (session claims either from id token or from profile URL) +* `secretSource` - `value` (base64), `fromFile` (file path) + +**Request option:** `preserveRequestValue: true` retains existing header values + +**Incompatibility:** Remove legacy flags `pass-user-headers`, `set-xauthrequest` + ## Removed options The following flags/options and their respective environment variables are no diff --git a/docs/versioned_docs/version-7.14.x/configuration/alpha_config.md.tmpl b/docs/versioned_docs/version-7.14.x/configuration/alpha_config.md.tmpl index 8258201f..081657c4 100644 --- a/docs/versioned_docs/version-7.14.x/configuration/alpha_config.md.tmpl +++ b/docs/versioned_docs/version-7.14.x/configuration/alpha_config.md.tmpl @@ -24,17 +24,56 @@ When using alpha configuration, your config file will look something like below: upstreams: - id: ... ...: ... +providers: + - id: ... + ...: ... +cookie: + secret: ... + ...: ... injectRequestHeaders: - - name: ... - ...: ... + - secretSource: + ...: ... injectResponseHeaders: - - name: ... - ...: ... + - claimSource: + ...: ... ``` Please browse the [reference](#configuration-reference) below for the structure of the new configuration format. +# Migration Guide + +This section details breaking changes and migration steps for moving to the new +alpha configuration format. + +## Migrating header injections in v7.14.0 + +From v7.14.0 onward, header injection sources must be explicitly nested. If you +previously relied on squashed fields, update to the new structure before +upgrading: + +```yaml +# before v7.14.0 +injectRequestHeaders: +- name: X-Forwarded-User + values: + - claim: user +- name: X-Custom-Secret-header + values: + - value: my-super-secret + +# v7.14.0 and later +injectRequestHeaders: +- name: X-Forwarded-User + values: + - claimSource: + claim: user +- name: X-Custom-Secret-header + values: + - secretSource: + value: my-super-secret +``` + ## Using Alpha Configuration To use the new **alpha** configuration, generate a YAML file based on the format @@ -67,9 +106,9 @@ the new config. oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg ``` -## Using ENV variables in the alpha configuration +### How to use environment variables -The alpha package supports the use of environment variables in place of yaml keys, allowing sensitive values to be pulled from somewhere other than the yaml file. +The alpha package supports the use of environment variables in place of yaml values, allowing sensitive data to be pulled from somewhere other than the yaml file. When using environment variables, your yaml will look like this: ```yaml @@ -81,6 +120,46 @@ When using environment variables, your yaml will look like this: Where CLIENT_SECRET is an environment variable. More information and available patterns can be found [here](https://github.com/a8m/envsubst#docs) +### How to inject custom headers + +Configure `injectRequestHeaders` and `injectResponseHeaders` in alpha config YAML. + +```yaml +injectRequestHeaders: + - name: "X-User-Email" + values: + - claimSource: + claim: "email" # extract the email claim contents from the id token + - name: "X-Static-Secret" + values: + # secrets need to be encoded with base64 when directly in the yaml config but will be send decoded + - secretSource: + value: "c3VwZXItc2VjcmV0" + - name: "X-Static-File-Secret" + - secretSource: + fromFile: "/path/to/my/secret" + - name: "X-Static-Env-Secret" + - secretSource: + value: "${MY_SECRET_ENV}" # content still needs to be base64 encoded +injectResponseHeaders: + # Following will result in a header "Authorization: Basic (encoded)" + - name: "Authorization" + values: + - claimSource: + claim: user + prefix: "Basic " + basicAuthPassword: + value: c3VwZXItc2VjcmV0LXBhc3N3b3Jk # base64 encoded password +``` + +**Value sources:** +* `claimSource` - `claim` (session claims either from id token or from profile URL) +* `secretSource` - `value` (base64), `fromFile` (file path) + +**Request option:** `preserveRequestValue: true` retains existing header values + +**Incompatibility:** Remove legacy flags `pass-user-headers`, `set-xauthrequest` + ## Removed options The following flags/options and their respective environment variables are no