doc: add changelog and migration guide for v7.14.0 alpha config changes
Signed-off-by: Jan Larwig <jan@larwig.com>
This commit is contained in:
Jan Larwig
parent
3124bf7bda
commit
34c2712c99
47
CHANGELOG.md
47
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <user:password> (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
|
||||
|
|
|
|||
|
|
@ -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 <user:password> (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
|
||||
|
|
|
|||
|
|
@ -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 <user:password> (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
|
||||
|
|
|
|||
|
|
@ -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 <user:password> (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
|
||||
|
|
|
|||
Loading…
Reference in New Issue