@@ -0,0 +1,212 @@
1+---
2+id: alpha-config
3+title: Alpha Configuration
4+---
5+
6+:::warning
7+This page contains documentation for alpha features.
8+We reserve the right to make breaking changes to the features detailed within this page with no notice.
9+
10+Options described in this page may be changed, removed, renamed or moved without prior warning.
11+Please beware of this before you use alpha configuration options.
12+:::
13+
14+This page details a set of **alpha** configuration options in a new format.
15+Going forward we are intending to add structured configuration in YAML format to
16+replace the existing TOML based configuration file and flags.
17+
18+Below is a reference for the structure of the configuration, with
19+[AlphaOptions](#alphaoptions) as the root of the configuration.
20+
21+When using alpha configuration, your config file will look something like below:
22+
23+```yaml
24+upstreams:
25+ - id: ...
26+ ...
27+injectRequestHeaders:
28+ - name: ...
29+ ...
30+injectResponseHeaders:
31+ - name: ...
32+ ...
33+```
34+
35+Please browse the [reference](#configuration-reference) below for the structure
36+of the new configuration format.
37+
38+## Using Alpha Configuration
39+
40+To use the new **alpha** configuration, generate a YAML file based on the format
41+described in the [reference](#configuration-reference) below.
42+
43+Provide the path to this file using the `--alpha-config` flag.
44+
45+:::note
46+When using the `--alpha-config` flag, some options are no longer available.
47+See [removed options](#removed-options) below for more information.
48+:::
49+
50+### Converting configuration to the new structure
51+
52+Before adding the new `--alpha-config` option, start OAuth2 Proxy using the
53+`convert-config-to-alpha` flag to convert existing configuration to the new format.
54+
55+```bash
56+oauth2-proxy --convert-config-to-alpha --config ./path/to/existing/config.cfg
57+```
58+
59+This will convert any options supported by the new format to YAML and print the
60+new configuration to `STDOUT`.
61+
62+Copy this to a new file, remove any options from your existing configuration
63+noted in [removed options](#removed-options) and then start OAuth2 Proxy using
64+the new config.
65+
66+```bash
67+oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg
68+```
69+
70+## Removed options
71+
72+The following flags/options and their respective environment variables are no
73+longer available when using alpha configuration:
74+
75+<!-- Legacy Upstream FlagSet -->
76+- `flush-interval`/`flush_interval`
77+- `pass-host-header`/`pass_host_header`
78+- `proxy-websockets`/`proxy_websockets`
79+- `ssl-upstream-insecure-skip-verify`/`ssl_upstream_insecure_skip_verify`
80+- `upstream`/`upstreams`
81+
82+<!-- Legacy Headers FlagSet -->
83+- `pass-basic-auth`/`pass_basic_auth`
84+- `pass-access-token`/`pass_access_token`
85+- `pass-user-headers`/`pass_user_headers`
86+- `pass-authorization-header`/`pass_authorization_header`
87+- `set-basic-auth`/`set_basic_auth`
88+- `set-xauthrequest`/`set_xauthrequest`
89+- `set-authorization-header`/`set_authorization_header`
90+- `prefer-email-to-user`/`prefer_email_to_user`
91+- `basic-auth-password`/`basic_auth_password`
92+- `skip-auth-strip-headers`/`skip_auth_strip_headers`
93+
94+Attempting to use these options via flags or via config when `--alpha-config`
95+set will result in an error.
96+
97+:::important
98+You must remove these options before starting OAuth2 Proxy with `--alpha-config`
99+:::
100+
101+## Configuration Reference
102+<!--- THIS FILE IS AUTOGENERATED!!! DO NOT EDIT!!! -->
103+
104+### AlphaOptions
105+
106+AlphaOptions contains alpha structured configuration options.
107+Usage of these options allows users to access alpha features that are not
108+available as part of the primary configuration structure for OAuth2 Proxy.
109+
110+:::warning
111+The options within this structure are considered alpha.
112+They may change between releases without notice.
113+:::
114+
115+| Field | Type | Description |
116+| ----- | ---- | ----------- |
117+| `upstreams` | _[Upstreams](#upstreams)_ | Upstreams is used to configure upstream servers.<br/>Once a user is authenticated, requests to the server will be proxied to<br/>these upstream servers based on the path mappings defined in this list. |
118+| `injectRequestHeaders` | _[[]Header](#header)_ | InjectRequestHeaders is used to configure headers that should be added<br/>to requests to upstream servers.<br/>Headers may source values from either the authenticated user's session<br/>or from a static secret value. |
119+| `injectResponseHeaders` | _[[]Header](#header)_ | InjectResponseHeaders is used to configure headers that should be added<br/>to responses from the proxy.<br/>This is typically used when using the proxy as an external authentication<br/>provider in conjunction with another proxy such as NGINX and its<br/>auth_request module.<br/>Headers may source values from either the authenticated user's session<br/>or from a static secret value. |
120+
121+### ClaimSource
122+
123+(**Appears on:** [HeaderValue](#headervalue))
124+
125+ClaimSource allows loading a header value from a claim within the session
126+
127+| Field | Type | Description |
128+| ----- | ---- | ----------- |
129+| `claim` | _string_ | Claim is the name of the claim in the session that the value should be<br/>loaded from. |
130+| `prefix` | _string_ | Prefix is an optional prefix that will be prepended to the value of the<br/>claim if it is non-empty. |
131+| `basicAuthPassword` | _[SecretSource](#secretsource)_ | BasicAuthPassword converts this claim into a basic auth header.<br/>Note the value of claim will become the basic auth username and the<br/>basicAuthPassword will be used as the password value. |
132+
133+### Duration
134+#### (`string` alias)
135+
136+(**Appears on:** [Upstream](#upstream))
137+
138+Duration is as string representation of a period of time.
139+A duration string is a is a possibly signed sequence of decimal numbers,
140+each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
141+Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
142+
143+
144+### Header
145+
146+(**Appears on:** [AlphaOptions](#alphaoptions))
147+
148+Header represents an individual header that will be added to a request or
149+response header.
150+
151+| Field | Type | Description |
152+| ----- | ---- | ----------- |
153+| `name` | _string_ | Name is the header name to be used for this set of values.<br/>Names should be unique within a list of Headers. |
154+| `preserveRequestValue` | _bool_ | PreserveRequestValue determines whether any values for this header<br/>should be preserved for the request to the upstream server.<br/>This option only takes effet on injected request headers.<br/>Defaults to false (headers that match this header will be stripped). |
155+| `values` | _[[]HeaderValue](#headervalue)_ | Values contains the desired values for this header |
156+
157+### HeaderValue
158+
159+(**Appears on:** [Header](#header))
160+
161+HeaderValue represents a single header value and the sources that can
162+make up the header value
163+
164+| Field | Type | Description |
165+| ----- | ---- | ----------- |
166+| `value` | _[]byte_ | Value expects a base64 encoded string value. |
167+| `fromEnv` | _string_ | FromEnv expects the name of an environment variable. |
168+| `fromFile` | _string_ | FromFile expects a path to a file containing the secret value. |
169+| `claim` | _string_ | Claim is the name of the claim in the session that the value should be<br/>loaded from. |
170+| `prefix` | _string_ | Prefix is an optional prefix that will be prepended to the value of the<br/>claim if it is non-empty. |
171+| `basicAuthPassword` | _[SecretSource](#secretsource)_ | BasicAuthPassword converts this claim into a basic auth header.<br/>Note the value of claim will become the basic auth username and the<br/>basicAuthPassword will be used as the password value. |
172+
173+### SecretSource
174+
175+(**Appears on:** [ClaimSource](#claimsource), [HeaderValue](#headervalue))
176+
177+SecretSource references an individual secret value.
178+Only one source within the struct should be defined at any time.
179+
180+| Field | Type | Description |
181+| ----- | ---- | ----------- |
182+| `value` | _[]byte_ | Value expects a base64 encoded string value. |
183+| `fromEnv` | _string_ | FromEnv expects the name of an environment variable. |
184+| `fromFile` | _string_ | FromFile expects a path to a file containing the secret value. |
185+
186+### Upstream
187+
188+(**Appears on:** [Upstreams](#upstreams))
189+
190+Upstream represents the configuration for an upstream server.
191+Requests will be proxied to this upstream if the path matches the request path.
192+
193+| Field | Type | Description |
194+| ----- | ---- | ----------- |
195+| `id` | _string_ | ID should be a unique identifier for the upstream.<br/>This value is required for all upstreams. |
196+| `path` | _string_ | Path is used to map requests to the upstream server.<br/>The closest match will take precedence and all Paths must be unique. |
197+| `uri` | _string_ | The URI of the upstream server. This may be an HTTP(S) server of a File<br/>based URL. It may include a path, in which case all requests will be served<br/>under that path.<br/>Eg:<br/>- http://localhost:8080<br/>- https://service.localhost<br/>- https://service.localhost/path<br/>- file://host/path<br/>If the URI's path is "/base" and the incoming request was for "/dir",<br/>the upstream request will be for "/base/dir". |
198+| `insecureSkipTLSVerify` | _bool_ | InsecureSkipTLSVerify will skip TLS verification of upstream HTTPS hosts.<br/>This option is insecure and will allow potential Man-In-The-Middle attacks<br/>betweem OAuth2 Proxy and the usptream server.<br/>Defaults to false. |
199+| `static` | _bool_ | Static will make all requests to this upstream have a static response.<br/>The response will have a body of "Authenticated" and a response code<br/>matching StaticCode.<br/>If StaticCode is not set, the response will return a 200 response. |
200+| `staticCode` | _int_ | StaticCode determines the response code for the Static response.<br/>This option can only be used with Static enabled. |
201+| `flushInterval` | _[Duration](#duration)_ | FlushInterval is the period between flushing the response buffer when<br/>streaming response from the upstream.<br/>Defaults to 1 second. |
202+| `passHostHeader` | _bool_ | PassHostHeader determines whether the request host header should be proxied<br/>to the upstream server.<br/>Defaults to true. |
203+| `proxyWebSockets` | _bool_ | ProxyWebSockets enables proxying of websockets to upstream servers<br/>Defaults to true. |
204+
205+### Upstreams
206+
207+#### ([[]Upstream](#upstream) alias)
208+
209+(**Appears on:** [AlphaOptions](#alphaoptions))
210+
211+Upstreams is a collection of definitions for upstream servers.
212+