We reserve the right to make breaking changes to the features detailed within this page with no notice.</p><p>Options described in this page may be changed, removed, renamed or moved without prior warning.
Please beware of this before you use alpha configuration options.</p></div></div><p>This page details a set of <strong>alpha</strong> configuration options in a new format.
Going forward we are intending to add structured configuration in YAML format to
replace the existing TOML based configuration file and flags.</p><p>Below is a reference for the structure of the configuration, with
<ahref="#alphaoptions">AlphaOptions</a> as the root of the configuration.</p><p>When using alpha configuration, your config file will look something like below:</p><divclass="mdxCodeBlock_1XEh"><divclass="codeBlockContent_1u-d"><buttontabindex="0"type="button"aria-label="Copy code to clipboard"class="copyButton_10dd">Copy</button><divclass="prism-code language-yaml codeBlock_3iAC"><divclass="codeBlockLines_b7E3"style="color:#bfc7d5;background-color:#292d3e"><divclass="token-line"style="color:#bfc7d5"><spanclass="token key atrule">upstreams</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain"></span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">-</span><spanclass="token plain"></span><spanclass="token key atrule">id</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">...</span><spanclass="token plain"></span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">...</span><spanclass="token plain"></span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token key atrule">injectRequestHeaders</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain"></span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">-</span><spanclass="token plain"></span><spanclass="token key atrule">name</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">...</span><spanclass="token plain"></span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">...</span><spanclass="token plain"></span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token key atrule">injectResponseHeaders</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain"></span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">-</span><spanclass="token plain"></span><spanclass="token key atrule">name</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">...</span><spanclass="token plain"></span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">...</span></div></div></div></div></div><p>Please browse the <ahref="#configuration-reference">reference</a> below for the structure
of the new configuration format.</p><h2><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="using-alpha-configuration"></a>Using Alpha Configuration<aaria-hidden="true"tabindex="-1"class="hash-link"href="#using-alpha-configuration"title="Direct link to heading">#</a></h2><p>To use the new <strong>alpha</strong> configuration, generate a YAML file based on the format
described in the <ahref="#configuration-reference">reference</a> below.</p><p>Provide the path to this file using the <code>--alpha-config</code> flag.</p><divclass="admonition admonition-note alert alert--secondary"><divclass="admonition-heading"><h5><spanclass="admonition-icon"><svgxmlns="http://www.w3.org/2000/svg"width="14"height="16"viewBox="0 0 14 16"><pathfill-rule="evenodd"d="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</h5></div><divclass="admonition-content"><p>When using the <code>--alpha-config</code> flag, some options are no longer available.
See <ahref="#removed-options">removed options</a> below for more information.</p></div></div><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="converting-configuration-to-the-new-structure"></a>Converting configuration to the new structure<aaria-hidden="true"tabindex="-1"class="hash-link"href="#converting-configuration-to-the-new-structure"title="Direct link to heading">#</a></h3><p>Before adding the new <code>--alpha-config</code> option, start OAuth2 Proxy using the
<code>convert-config-to-alpha</code> flag to convert existing configuration to the new format.</p><divclass="mdxCodeBlock_1XEh"><divclass="codeBlockContent_1u-d"><buttontabindex="0"type="button"aria-label="Copy code to clipboard"class="copyButton_10dd">Copy</button><divclass="prism-code language-bash codeBlock_3iAC"><divclass="codeBlockLines_b7E3"style="color:#bfc7d5;background-color:#292d3e"><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain">oauth2-proxy --convert-config-to-alpha --config ./path/to/existing/config.cfg</span></div></div></div></div></div><p>This will convert any options supported by the new format to YAML and print the
new configuration to <code>STDOUT</code>.</p><p>Copy this to a new file, remove any options from your existing configuration
noted in <ahref="#removed-options">removed options</a> and then start OAuth2 Proxy using
the new config.</p><divclass="mdxCodeBlock_1XEh"><divclass="codeBlockContent_1u-d"><buttontabindex="0"type="button"aria-label="Copy code to clipboard"class="copyButton_10dd">Copy</button><divclass="prism-code language-bash codeBlock_3iAC"><divclass="codeBlockLines_b7E3"style="color:#bfc7d5;background-color:#292d3e"><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain">oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg</span></div></div></div></div></div><h2><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="removed-options"></a>Removed options<aaria-hidden="true"tabindex="-1"class="hash-link"href="#removed-options"title="Direct link to heading">#</a></h2><p>The following flags/options and their respective environment variables are no
longer available when using alpha configuration:</p><ul><li><code>flush-interval</code>/<code>flush_interval</code></li><li><code>pass-host-header</code>/<code>pass_host_header</code></li><li><code>proxy-websockets</code>/<code>proxy_websockets</code></li><li><code>ssl-upstream-insecure-skip-verify</code>/<code>ssl_upstream_insecure_skip_verify</code></li><li><code>upstream</code>/<code>upstreams</code></li></ul><ul><li><code>pass-basic-auth</code>/<code>pass_basic_auth</code></li><li><code>pass-access-token</code>/<code>pass_access_token</code></li><li><code>pass-user-headers</code>/<code>pass_user_headers</code></li><li><code>pass-authorization-header</code>/<code>pass_authorization_header</code></li><li><code>set-basic-auth</code>/<code>set_basic_auth</code></li><li><code>set-xauthrequest</code>/<code>set_xauthrequest</code></li><li><code>set-authorization-header</code>/<code>set_authorization_header</code></li><li><code>prefer-email-to-user</code>/<code>prefer_email_to_user</code></li><li><code>basic-auth-password</code>/<code>basic_auth_password</code></li><li><code>skip-auth-strip-headers</code>/<code>skip_auth_strip_headers</code></li></ul><p>Attempting to use these options via flags or via config when <code>--alpha-config</code>
set will result in an error.</p><divclass="admonition admonition-important alert alert--info"><divclass="admonition-heading"><h5><spanclass="admonition-icon"><svgxmlns="http://www.w3.org/2000/svg"width="14"height="16"viewBox="0 0 14 16"><pathfill-rule="evenodd"d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 0 1 1.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg></span>important</h5></div><divclass="admonition-content"><p>You must remove these options before starting OAuth2 Proxy with <code>--alpha-config</code></p></div></div><h2><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="configuration-reference"></a>Configuration Reference<aaria-hidden="true"tabindex="-1"class="hash-link"href="#configuration-reference"title="Direct link to heading">#</a></h2><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="alphaoptions"></a>AlphaOptions<aaria-hidden="true"tabindex="-1"class="hash-link"href="#alphaoptions"title="Direct link to heading">#</a></h3><p>AlphaOptions contains alpha structured configuration options.
Usage of these options allows users to access alpha features that are not
available as part of the primary configuration structure for OAuth2 Proxy.</p><divclass="admonition admonition-warning alert alert--danger"><divclass="admonition-heading"><h5><spanclass="admonition-icon"><svgxmlns="http://www.w3.org/2000/svg"width="12"height="16"viewBox="0 0 12 16"><pathfill-rule="evenodd"d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"></path></svg></span>warning</h5></div><divclass="admonition-content"><p>The options within this structure are considered alpha.
They may change between releases without notice.</p></div></div><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>upstreams</code></td><td><em><ahref="#upstreams">Upstreams</a></em></td><td>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.</td></tr><tr><td><code>injectRequestHeaders</code></td><td><em><ahref="#header">[]Header</a></em></td><td>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.</td></tr><tr><td><code>injectResponseHeaders</code></td><td><em><ahref="#header">[]Header</a></em></td><td>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.</td></tr></tbody></table><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="claimsource"></a>ClaimSource<aaria-hidden="true"tabindex="-1"class="hash-link"href="#claimsource"title="Direct link to heading">#</a></h3><p>(<strong>Appears on:</strong><ahref="#headervalue">HeaderValue</a>)</p><p>ClaimSource allows loading a header value from a claim within the session</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>claim</code></td><td><em>string</em></td><td>Claim is the name of the claim in the session that the value should be<br>loaded from.</td></tr><tr><td><code>prefix</code></td><td><em>string</em></td><td>Prefix is an optional prefix that will be prepended to the value of the<br>claim if it is non-empty.</td></tr><tr><td><code>basicAuthPassword</code></td><td><em><ahref="#secretsource">SecretSource</a></em></td><td>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.</td></tr></tbody></table><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="duration"></a>Duration<aaria-hidden="true"tabindex="-1"class="hash-link"href="#duration"title="Direct link to heading">#</a></h3><h4><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="string-alias"></a>(<code>string</code> alias)<aaria-hidden="true"tabindex="-1"class="hash-link"href="#string-alias"title="Direct link to heading">#</a></h4><p>(<strong>Appears on:</strong><ahref="#upstream">Upstream</a>)</p><p>Duration is as string representation of a period of time.
A duration string is a is a possibly signed sequence of decimal numbers,
each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m".
Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".</p><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="header"></a>Header<aaria-hidden="true"tabindex="-1"class="hash-link"href="#header"title="Direct link to heading">#</a></h3><p>(<strong>Appears on:</strong><ahref="#alphaoptions">AlphaOptions</a>)</p><p>Header represents an individual header that will be added to a request or
response header.</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td><em>string</em></td><td>Name is the header name to be used for this set of values.<br>Names should be unique within a list of Headers.</td></tr><tr><td><code>preserveRequestValue</code></td><td><em>bool</em></td><td>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).</td></tr><tr><td><code>values</code></td><td><em><ahref="#headervalue">[]HeaderValue</a></em></td><td>Values contains the desired values for this header</td></tr></tbody></table><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="headervalue"></a>HeaderValue<aaria-hidden="true"tabindex="-1"class="hash-link"href="#headervalue"title="Direct link to heading">#</a></h3><p>(<strong>Appears on:</strong><ahref="#header">Header</a>)</p><p>HeaderValue represents a single header value and the sources that can
make up the header value</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>value</code></td><td><em>[]byte</em></td><td>Value expects a base64 encoded string value.</td></tr><tr><td><code>fromEnv</code></td><td><em>string</em></td><td>FromEnv expects the name of an environment variable.</td></tr><tr><td><code>fromFile</code></td><td><em>string</em></td><td>FromFile expects a path to a file containing the secret value.</td></tr><tr><td><code>claim</code></td><td><em>string</em></td><td>Claim is the name of the claim in the session that the value should be<br>loaded from.</td></tr><tr><td><code>prefix</code></td><td><em>string</em></td><td>Prefix is an optional prefix that will be prepended to the value of the<br>claim if it is non-empty.</td></tr><tr><td><code>basicAuthPassword</code></td><td><em><ahref="#secretsource">SecretSource</a></em></td><td>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.</td></tr></tbody></table><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="secretsource"></a>SecretSource<aaria-hidden="true"tabindex="-1"class="hash-link"href="#secretsource"title="Direct link to heading">#</a></h3><p>(<strong>Appears on:</strong><ahref="#claimsource">ClaimSource</a>, <ahref="#headervalue">HeaderValue</a>)</p><p>SecretSource references an individual secret value.
Only one source within the struct should be defined at any time.</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>value</code></td><td><em>[]byte</em></td><td>Value expects a base64 encoded string value.</td></tr><tr><td><code>fromEnv</code></td><td><em>string</em></td><td>FromEnv expects the name of an environment variable.</td></tr><tr><td><code>fromFile</code></td><td><em>string</em></td><td>FromFile expects a path to a file containing the secret value.</td></tr></tbody></table><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="upstream"></a>Upstream<aaria-hidden="true"tabindex="-1"class="hash-link"href="#upstream"title="Direct link to heading">#</a></h3><p>(<strong>Appears on:</strong><ahref="#upstreams">Upstreams</a>)</p><p>Upstream represents the configuration for an upstream server.
Requests will be proxied to this upstream if the path matches the request path.</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td><em>string</em></td><td>ID should be a unique identifier for the upstream.<br>This value is required for all upstreams.</td></tr><tr><td><code>path</code></td><td><em>string</em></td><td>Path is used to map requests to the upstream server.<br>The closest match will take precedence and all Paths must be unique.</td></tr><tr><td><code>uri</code></td><td><em>string</em></td><td>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>- <ahref="https://service.localhost"target="_blank"rel="noopener noreferrer">https://service.localhost</a><br>- <ahref="https://service.localhost/path"target="_blank"rel="noopener noreferrer">https://service.localhost/path</a><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".</td></tr><tr><td><code>insecureSkipTLSVerify</code></td><td><em>bool</em></td><td>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.</td></tr><tr><td><code>static</code></td><td><em>bool</em></td><td>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.</td></tr><tr><td><code>staticCode</code></td><td><em>int</em></td><td>StaticCode determines the response code for the Static response.<br>This option can only be used with Static enabled.</td></tr><tr><td><code>flushInterval</code></td><td><em><ahref="#duration">Duration</a></em></td><td>FlushInterval is the period between flushing the response buffer when<br>streaming response from the upstream.<br>Defaults to 1 second.</td></tr><tr><td><code>passHostHeader</code></td><td><em>bool</em></td><td>PassHostHeader determines whether the request host header should be proxied<br>to the upstream server.<br>Defaults to true.</td></tr><tr><td><code>proxyWebSockets</code></td><td><em>bool</em></td><td>ProxyWebSockets enables proxying of websockets to upstream servers<br>Defaults to true.</td></tr></tbody></table><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="upstreams"></a>Upstreams<aaria-hidden="true"tabindex="-1"class="hash-link"href="#upstreams"title="Direct link to heading">#</a></h3><h4><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="upstream-alias"></a>(<ahref="#upstream">[]Upstream</a> alias)<aaria-hidden="true"tabindex="-1"class="hash-link"href="#upstream-alias"title="Direct link to heading">#</a></h4><p>(<strong>Appears on:</strong><ahref="#alphaoptions">AlphaOptions</a>)</p><p>Upstreams is a collection of definitions for upstream servers.</p></div></article><divclass="margin-vert--xl"><divclass="row"><divclass="col"><ahref="https://github.com/oauth2-proxy/oauth2-proxy/edit/master/docs/versioned_docs/version-7.0.x/configuration/alpha_config.md"target="_blank"rel="noreferrer noopener"><svgfill="currentColor"height="1.2em"width="1.2em"preserveAspectRatio="xMidYMid meet"viewBox="0 0 40 40"style="margin-right:0.3em;vertical-align:sub"><g><pathd="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div></div></div><divclass="margin-vert--lg"><navclass="pagination-nav"aria-label="Blog list page navigation"><divclass="pagination-nav__item"><aclass="pagination-nav__link"href="/oauth2-proxy/docs/configuration/tls"><divclass="paginatio
