@@ -24,17 +24,56 @@ When using alpha configuration, your config file will look something like below:
2424upstreams:
2525 - id: ...
2626 ...: ...
27−injectRequestHeaders:
28− - name: ...
27+providers:
28+ - id: ...
2929 ...: ...
30+cookie:
31+ secret: ...
32+ ...: ...
33+injectRequestHeaders:
34+ - secretSource:
35+ ...: ...
3036injectResponseHeaders:
31− - name: ...
32− ...: ...
37+ - claimSource:
38+ ...: ...
3339```
3440
3541Please browse the [reference](#configuration-reference) below for the structure
3642of the new configuration format.
3743
44+# Migration Guide
45+
46+This section details breaking changes and migration steps for moving to the new
47+alpha configuration format.
48+
49+## Migrating header injections in v7.14.0
50+
51+From v7.14.0 onward, header injection sources must be explicitly nested. If you
52+previously relied on squashed fields, update to the new structure before
53+upgrading:
54+
55+```yaml
56+# before v7.14.0
57+injectRequestHeaders:
58+- name: X-Forwarded-User
59+ values:
60+ - claim: user
61+- name: X-Custom-Secret-header
62+ values:
63+ - value: my-super-secret
64+
65+# v7.14.0 and later
66+injectRequestHeaders:
67+- name: X-Forwarded-User
68+ values:
69+ - claimSource:
70+ claim: user
71+- name: X-Custom-Secret-header
72+ values:
73+ - secretSource:
74+ value: my-super-secret
75+```
76+
3877## Using Alpha Configuration
3978
4079To use the new **alpha** configuration, generate a YAML file based on the format
@@ -67,9 +106,9 @@ the new config.
67106oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg
68107```
69108
70−## Using ENV variables in the alpha configuration
109+### How to use environment variables
71110
72−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.
111+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.
73112When using environment variables, your yaml will look like this:
74113
75114```yaml
@@ -81,6 +120,46 @@ When using environment variables, your yaml will look like this:
81120Where CLIENT_SECRET is an environment variable.
82121More information and available patterns can be found [here](https://github.com/a8m/envsubst#docs)
83122
123+### How to inject custom headers
124+
125+Configure `injectRequestHeaders` and `injectResponseHeaders` in alpha config YAML.
126+
127+```yaml
128+injectRequestHeaders:
129+ - name: "X-User-Email"
130+ values:
131+ - claimSource:
132+ claim: "email" # extract the email claim contents from the id token
133+ - name: "X-Static-Secret"
134+ values:
135+ # secrets need to be encoded with base64 when directly in the yaml config but will be send decoded
136+ - secretSource:
137+ value: "c3VwZXItc2VjcmV0"
138+ - name: "X-Static-File-Secret"
139+ - secretSource:
140+ fromFile: "/path/to/my/secret"
141+ - name: "X-Static-Env-Secret"
142+ - secretSource:
143+ value: "${MY_SECRET_ENV}" # content still needs to be base64 encoded
144+injectResponseHeaders:
145+ # Following will result in a header "Authorization: Basic <user:password> (encoded)"
146+ - name: "Authorization"
147+ values:
148+ - claimSource:
149+ claim: user
150+ prefix: "Basic "
151+ basicAuthPassword:
152+ value: c3VwZXItc2VjcmV0LXBhc3N3b3Jk # base64 encoded password
153+```
154+
155+**Value sources:**
156+* `claimSource` - `claim` (session claims either from id token or from profile URL)
157+* `secretSource` - `value` (base64), `fromFile` (file path)
158+
159+**Request option:** `preserveRequestValue: true` retains existing header values
160+
161+**Incompatibility:** Remove legacy flags `pass-user-headers`, `set-xauthrequest`
162+
84163## Removed options
85164
86165The following flags/options and their respective environment variables are no