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="codeBlockContainer_I0IT language-yaml theme-code-block"><divclass="codeBlockContent_wNvx yaml"><pretabindex="0"class="prism-code language-yaml codeBlock_jd64 thin-scrollbar"style="color:#bfc7d5;background-color:#292d3e"><codeclass="codeBlockLines_mRuA"><spanclass="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><br></span><spanclass="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><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">...</span><spanclass="token plain"></span><br></span><spanclass="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><br></span><spanclass="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><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">...</span><spanclass="token plain"></span><br></span><spanclass="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><br></span><spanclass="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><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">...</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>Please browse the <ahref="#configuration-reference">reference</a> below for the structure
of the new configuration format.</p><h2class="anchor anchorWithStickyNavbar_mojV"id="using-alpha-configuration">Using Alpha Configuration<aclass="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
See <ahref="#removed-options">removed options</a> below for more information.</p></div></div><h3class="anchor anchorWithStickyNavbar_mojV"id="converting-configuration-to-the-new-structure">Converting configuration to the new structure<aclass="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="codeBlockContainer_I0IT language-bash theme-code-block"><divclass="codeBlockContent_wNvx bash"><pretabindex="0"class="prism-code language-bash codeBlock_jd64 thin-scrollbar"style="color:#bfc7d5;background-color:#292d3e"><codeclass="codeBlockLines_mRuA"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">oauth2-proxy --convert-config-to-alpha --config ./path/to/existing/config.cfg</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>This will convert any options supported by the new format to YAML and print the
the new config.</p><divclass="codeBlockContainer_I0IT language-bash theme-code-block"><divclass="codeBlockContent_wNvx bash"><pretabindex="0"class="prism-code language-bash codeBlock_jd64 thin-scrollbar"style="color:#bfc7d5;background-color:#292d3e"><codeclass="codeBlockLines_mRuA"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></div></div><h2class="anchor anchorWithStickyNavbar_mojV"id="removed-options">Removed options<aclass="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><ul><li><code>client-id</code>/<code>client_id</code></li><li><code>client-secret</code>/<code>client_secret</code>, and <code>client-secret-file</code>/<code>client_secret_file</code></li><li><code>provider</code></li><li><code>provider-display-name</code>/<code>provider_display_name</code></li><li><code>provider-ca-file</code>/<code>provider_ca_files</code></li><li><code>login-url</code>/<code>login_url</code></li><li><code>redeem-url</code>/<code>redeem_url</code></li><li><code>profile-url</code>/<code>profile_url</code></li><li><code>resource</code></li><li><code>validate-url</code>/<code>validate_url</code></li><li><code>scope</code></li><li><code>prompt</code></li><li><code>approval-prompt</code>/<code>approval_prompt</code></li><li><code>acr-values</code>/<code>acr_values</code></li><li><code>user-id-claim</code>/<code>user_id_claim</code></li><li><code>allowed-group</code>/<code>allowed_groups</code></li><li><code>allowed-role</code>/<code>allowed_roles</code></li><li><code>jwt-key</code>/<code>jwt_key</code></li><li><code>jwt-key-file</code>/<code>jwt_key_file</code></li><li><code>pubjwk-url</code>/<code>pubjwk_url</code></li></ul><p>and all provider-specific options, i.e. any option whose name includes <code>oidc</code>,
<code>azure</code>, <code>bitbucket</code>, <code>github</code>, <code>gitlab</code>, <code>google</code> or <code>keycloak</code>. Attempting to
use any of these options via flags or via config when <code>--alpha-config</code> is
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><h2class="anchor anchorWithStickyNavbar_mojV"id="configuration-reference">Configuration Reference<aclass="hash-link"href="#configuration-reference"title="Direct link to heading"></a></h2><h3class="anchor anchorWithStickyNavbar_mojV"id="adfsoptions">ADFSOptions<aclass="hash-link"href="#adfsoptions"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#provider">Provider</a>)</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>skipScope</code></td><td><em>bool</em></td><td>Skip adding the scope parameter in login request<br>Default value is 'false'</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="alphaoptions">AlphaOptions<aclass="hash-link"href="#alphaoptions"title="Direct link to heading"></a></h3><p>AlphaOptions contains alpha structured configuration options.
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>upstreamConfig</code></td><td><em><ahref="#upstreamconfig">UpstreamConfig</a></em></td><td>UpstreamConfig 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><tr><td><code>server</code></td><td><em><ahref="#server">Server</a></em></td><td>Server is used to configure the HTTP(S) server for the proxy application.<br>You may choose to run both HTTP and HTTPS servers simultaneously.<br>This can be done by setting the BindAddress and the SecureBindAddress simultaneously.<br>To use the secure server you must configure a TLS certificate and key.</td></tr><tr><td><code>metricsServer</code></td><td><em><ahref="#server">Server</a></em></td><td>MetricsServer is used to configure the HTTP(S) server for metrics.<br>You may choose to run both HTTP and HTTPS servers simultaneously.<br>This can be done by setting the BindAddress and the SecureBindAddress simultaneously.<br>To use the secure server you must configure a TLS certificate and key.</td></tr><tr><td><code>providers</code></td><td><em><ahref="#providers">Providers</a></em></td><td>Providers is used to configure multiple providers.</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="azureoptions">AzureOptions<aclass="hash-link"href="#azureoptions"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#provider">Provider</a>)</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>tenant</code></td><td><em>string</em></td><td>Tenant directs to a tenant-specific or common (tenant-independent) endpoint<br>Default value is 'common'</td></tr><tr><td><code>graphGroupField</code></td><td><em>string</em></td><td>GraphGroupField configures the group field to be used when building the groups list from Microsoft Graph<br>Default value is 'id'</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="bitbucketoptions">BitbucketOptions<aclass="hash-link"href="#bitbucketoptions"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#provider">Provider</a>)</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>team</code></td><td><em>string</em></td><td>Team sets restrict logins to members of this team</td></tr><tr><td><code>repository</code></td><td><em>string</em></td><td>Repository sets restrict logins to user with access to this repository</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="claimsource">ClaimSource<aclass="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
Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".</p><h3class="anchor anchorWithStickyNavbar_mojV"id="githuboptions">GitHubOptions<aclass="hash-link"href="#githuboptions"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#provider">Provider</a>)</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>org</code></td><td><em>string</em></td><td>Org sets restrict logins to members of this organisation</td></tr><tr><td><code>team</code></td><td><em>string</em></td><td>Team sets restrict logins to members of this team</td></tr><tr><td><code>repo</code></td><td><em>string</em></td><td>Repo sets restrict logins to collaborators of this repository</td></tr><tr><td><code>token</code></td><td><em>string</em></td><td>Token is the token to use when verifying repository collaborators<br>it must have push access to the repository</td></tr><tr><td><code>users</code></td><td><em>[]string</em></td><td>Users allows users with these usernames to login<br>even if they do not belong to the specified org and team or collaborators</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="gitlaboptions">GitLabOptions<aclass="hash-link"href="#gitlaboptions"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#provider">Provider</a>)</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>group</code></td><td><em>[]string</em></td><td>Group sets restrict logins to members of this group</td></tr><tr><td><code>projects</code></td><td><em>[]string</em></td><td>Projects restricts logins to members of any of these projects</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="googleoptions">GoogleOptions<aclass="hash-link"href="#googleoptions"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#provider">Provider</a>)</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>group</code></td><td><em>[]string</em></td><td>Groups sets restrict logins to members of this google group</td></tr><tr><td><code>adminEmail</code></td><td><em>string</em></td><td>AdminEmail is the google admin to impersonate for api calls</td></tr><tr><td><code>serviceAccountJson</code></td><td><em>string</em></td><td>ServiceAccountJSON is the path to the service account json credentials</td></tr><tr><td><code>useApplicationDefaultCredentials</code></td><td><em>bool</em></td><td>UseApplicationDefaultCredentials is a boolean whether to use Application Default Credentials instead of a ServiceAccountJSON</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="header">Header<aclass="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 applies to 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><h3class="anchor anchorWithStickyNavbar_mojV"id="headervalue">HeaderValue<aclass="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><h3class="anchor anchorWithStickyNavbar_mojV"id="keycloakoptions">KeycloakOptions<aclass="hash-link"href="#keycloakoptions"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#provider">Provider</a>)</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>groups</code></td><td><em>[]string</em></td><td>Group enables to restrict login to members of indicated group</td></tr><tr><td><code>roles</code></td><td><em>[]string</em></td><td>Role enables to restrict login to users with role (only available when using the keycloak-oidc provider)</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="logingovoptions">LoginGovOptions<aclass="hash-link"href="#logingovoptions"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#provider">Provider</a>)</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>jwtKey</code></td><td><em>string</em></td><td>JWTKey is a private key in PEM format used to sign JWT,</td></tr><tr><td><code>jwtKeyFile</code></td><td><em>string</em></td><td>JWTKeyFile is a path to the private key file in PEM format used to sign the JWT</td></tr><tr><td><code>pubjwkURL</code></td><td><em>string</em></td><td>PubJWKURL is the JWK pubkey access endpoint</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="loginurlparameter">LoginURLParameter<aclass="hash-link"href="#loginurlparameter"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#provider">Provider</a>)</p><p>LoginURLParameter is the configuration for a single query parameter that
the caller provides it, and no value will be sent otherwise.</p><p>Examples:</p><h1>A parameter whose value is fixed</h1><divclass="codeBlockContainer_I0IT theme-code-block"><divclass="codeBlockContent_wNvx"><pretabindex="0"class="prism-code language-text codeBlock_jd64 thin-scrollbar"style="color:#bfc7d5;background-color:#292d3e"><codeclass="codeBlockLines_mRuA"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">name: organization</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">default:</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">- myorg</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>A parameter that is not passed by default, but may be set to one of a
fixed set of values</p><divclass="codeBlockContainer_I0IT theme-code-block"><divclass="codeBlockContent_wNvx"><pretabindex="0"class="prism-code language-text codeBlock_jd64 thin-scrollbar"style="color:#bfc7d5;background-color:#292d3e"><codeclass="codeBlockLines_mRuA"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">name: prompt</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">allow:</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">- value: login</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">- value: consent</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">- value: select_account</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>A parameter that is passed by default but may be overridden by one of
a fixed set of values</p><divclass="codeBlockContainer_I0IT theme-code-block"><divclass="codeBlockContent_wNvx"><pretabindex="0"class="prism-code language-text codeBlock_jd64 thin-scrollbar"style="color:#bfc7d5;background-color:#292d3e"><codeclass="codeBlockLines_mRuA"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">name: prompt</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">default: ["login"]</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">allow:</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">- value: consent</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">- value: select_account</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>A parameter that may be overridden, but only by values that match a
addresses in your organization's domain:</p><divclass="codeBlockContainer_I0IT theme-code-block"><divclass="codeBlockContent_wNvx"><pretabindex="0"class="prism-code language-text codeBlock_jd64 thin-scrollbar"style="color:#bfc7d5;background-color:#292d3e"><codeclass="codeBlockLines_mRuA"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">name: login_hint</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">allow:</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">- pattern: '^[^@]*@example\.com$'</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"># this allows at most one "@" sign, and requires "example.com" domain.</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>Note that the YAML rules around exactly which characters are allowed
use the "chomped block" format <code>|-</code>:</p><divclass="codeBlockContainer_I0IT theme-code-block"><divclass="codeBlockContent_wNvx"><pretabindex="0"class="prism-code language-text codeBlock_jd64 thin-scrollbar"style="color:#bfc7d5;background-color:#292d3e"><codeclass="codeBlockLines_mRuA"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> - pattern: |-</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> ^[^@]*@example\.com$</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"style="display:inline-block"></span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></div></div><p>The hyphen is important, a <code>|</code> block would have a trailing newline
character.</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 specifies the name of the query parameter.</td></tr><tr><td><code>default</code></td><td><em>[]string</em></td><td><em>(Optional)</em> Default specifies a default value or values that will be<br>passed to the IdP if not overridden.</td></tr><tr><td><code>allow</code></td><td><em><ahref="#urlparameterrule">[]URLParameterRule</a></em></td><td><em>(Optional)</em> Allow specifies rules about how the default (if any) may be<br>overridden via the query string to <code>/oauth2/start</code>. Only<br>values that match one or more of the allow rules will be<br>forwarded to the IdP.</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="oidcoptions">OIDCOptions<aclass="hash-link"href="#oidcoptions"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#provider">Provider</a>)</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>issuerURL</code></td><td><em>string</em></td><td>IssuerURL is the OpenID Connect issuer URL<br>eg: <ahref="https://accounts.google.com"target="_blank"rel="noopener noreferrer">https://accounts.google.com</a></td></tr><tr><td><code>insecureAllowUnverifiedEmail</code></td><td><em>bool</em></td><td>InsecureAllowUnverifiedEmail prevents failures if an email address in an id_token is not verified<br>default set to 'false'</td></tr><tr><td><code>insecureSkipIssuerVerification</code></td><td><em>bool</em></td><td>InsecureSkipIssuerVerification skips verification of ID token issuers. When false, ID Token Issuers must match the OIDC discovery URL<br>default set to 'false'</td></tr><tr><td><code>insecureSkipNonce</code></td><td><em>bool</em></td><td>InsecureSkipNonce skips verifying the ID Token's nonce claim that must match<br>the random nonce sent in the initial OAuth flow. Otherwise, the nonce is checked<br>after the initial OAuth redeem & subsequent token refreshes.<br>default set to 'true'<br>Warning: In a future release, this will change to 'false' by default for enhanced security.</td></tr><tr><td><code>skipDiscovery</code></td><td><em>bool</em></td><td>SkipDiscovery allows to skip OIDC discovery and use manually supplied Endpoints<br>default set to 'false'</td></tr><tr><td><code>jwksURL</code></td><td><em>string</em></td><td>JwksURL is the OpenID Connect JWKS URL<br>eg: <ahref="https://www.googleapis.com/oauth2/v3/certs"target="_blank"rel="noopener noreferrer">https://www.googleapis.com/oauth2/v3/certs</a></td></tr><tr><td><code>emailClaim</code></td><td><em>string</em></td><td>EmailClaim indicates which claim contains the user email,<br>default set to 'email'</td></tr><tr><td><code>groupsClaim</code></td><td><em>string</em></td><td>GroupsClaim indicates which claim contains the user groups<br>default set to 'groups'</td></tr><tr><td><code>userIDClaim</code></td><td><em>string</em></td><td>UserIDClaim indicates which claim contains the user ID<br>default set to 'email'</td></tr><tr><td><code>audienceClaims</code></td><td><em>[]string</em></td><td>AudienceClaim allows to define any claim that is verified against the client id<br>By default <code>aud</code> claim is used for verification.</td></tr><tr><td><code>extraAudiences</code></td><td><em>[]string</em></td><td>ExtraAudiences is a list of additional audiences that are allowed<br>to pass verification in addition to the client id.</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="provider">Provider<aclass="hash-link"href="#provider"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#providers">Providers</a>)</p><p>Provider holds all configuration for a single provider</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>clientID</code></td><td><em>string</em></td><td>ClientID is the OAuth Clie
and oidc.</p><h3class="anchor anchorWithStickyNavbar_mojV"id="providers">Providers<aclass="hash-link"href="#providers"title="Direct link to heading"></a></h3><h4class="anchor anchorWithStickyNavbar_mojV"id="provider-alias">(<ahref="#provider">[]Provider</a> alias)<aclass="hash-link"href="#provider-alias"title="Direct link to heading"></a></h4><p>(<strong>Appears on:</strong><ahref="#alphaoptions">AlphaOptions</a>)</p><p>Providers is a collection of definitions for providers.</p><h3class="anchor anchorWithStickyNavbar_mojV"id="secretsource">SecretSource<aclass="hash-link"href="#secretsource"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#claimsource">ClaimSource</a>, <ahref="#headervalue">HeaderValue</a>, <ahref="#tls">TLS</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><h3class="anchor anchorWithStickyNavbar_mojV"id="server">Server<aclass="hash-link"href="#server"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#alphaoptions">AlphaOptions</a>)</p><p>Server represents the configuration for an HTTP(S) server</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>BindAddress</code></td><td><em>string</em></td><td>BindAddress is the address on which to serve traffic.<br>Leave blank or set to "-" to disable.</td></tr><tr><td><code>SecureBindAddress</code></td><td><em>string</em></td><td>SecureBindAddress is the address on which to serve secure traffic.<br>Leave blank or set to "-" to disable.</td></tr><tr><td><code>TLS</code></td><td><em><ahref="#tls">TLS</a></em></td><td>TLS contains the information for loading the certificate and key for the<br>secure traffic and further configuration for the TLS server.</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="tls">TLS<aclass="hash-link"href="#tls"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#server">Server</a>)</p><p>TLS contains the information for loading a TLS certificate and key
as well as an optional minimal TLS version that is acceptable.</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>Key</code></td><td><em><ahref="#secretsource">SecretSource</a></em></td><td>Key is the TLS key data to use.<br>Typically this will come from a file.</td></tr><tr><td><code>Cert</code></td><td><em><ahref="#secretsource">SecretSource</a></em></td><td>Cert is the TLS certificate data to use.<br>Typically this will come from a file.</td></tr><tr><td><code>MinVersion</code></td><td><em>string</em></td><td>MinVersion is the minimal TLS version that is acceptable.<br>E.g. Set to "TLS1.3" to select TLS version 1.3</td></tr><tr><td><code>CipherSuites</code></td><td><em>[]string</em></td><td>CipherSuites is a list of TLS cipher suites that are allowed.<br>E.g.:<br>- TLS_RSA_WITH_RC4_128_SHA<br>- TLS_RSA_WITH_AES_256_GCM_SHA384<br>If not specified, the default Go safe cipher list is used.<br>List of valid cipher suites can be found in the <ahref="https://pkg.go.dev/crypto/tls#pkg-constants"target="_blank"rel="noopener noreferrer">crypto/tls documentation</a>.</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="urlparameterrule">URLParameterRule<aclass="hash-link"href="#urlparameterrule"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#loginurlparameter">LoginURLParameter</a>)</p><p>URLParameterRule represents a rule by which query parameters
login URL. Either Value or Pattern should be supplied, not both.</p><table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>value</code></td><td><em>string</em></td><td>A Value rule matches just this specific value</td></tr><tr><td><code>pattern</code></td><td><em>string</em></td><td>A Pattern rule gives a regular expression that must be matched by<br>some substring of the value. The expression is <em>not</em> automatically<br>anchored to the start and end of the value, if you <em>want</em> to restrict<br>the whole parameter value you must anchor it yourself with <code>^</code> and <code>$</code>.</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="upstream">Upstream<aclass="hash-link"href="#upstream"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#upstreamconfig">UpstreamConfig</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.<br>Path can also take a pattern when used with RewriteTarget.<br>Path segments can be captured and matched using regular experessions.<br>Eg:<br>- <code>^/foo$</code>: Match only the explicit path <code>/foo</code><br>- <code>^/bar/$</code>: Match any path prefixed with <code>/bar/</code><br>- <code>^/baz/(.*)$</code>: Match any path prefixed with <code>/baz</code> and capture the remaining path for use with RewriteTarget</td></tr><tr><td><code>rewriteTarget</code></td><td><em>string</em></td><td>RewriteTarget allows users to rewrite the request path before it is sent to<br>the upstream server.<br>Use the Path to capture segments for reuse within the rewrite target.<br>Eg: With a Path of <code>^/baz/(.*)</code>, a RewriteTarget of <code>/foo/$1</code> would rewrite<br>the request <code>/baz/abc/123</code> to <code>/foo/abc/123</code> before proxying to the<br>upstream server.</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><tr><td><code>timeout</code></td><td><em><ahref="#duration">Duration</a></em></td><td>Timeout is the maximum duration the server will wait for a response from the upstream server.<br>Defaults to 30 seconds.</td></tr></tbody></table><h3class="anchor anchorWithStickyNavbar_mojV"id="upstreamconfig">UpstreamConfig<aclass="hash-link"href="#upstreamconfig"title="Direct link to heading"></a></h3><p>(<strong>Appears on:</strong><ahref="#alphaoptions">AlphaOptions</a>)</p><p>UpstreamConfig is a collection of definitions for upstream servers.</p><table><thead><tr><th>Field</th><th>Ty
