<titledata-react-helmet="true">Overview | OAuth2 Proxy</title><metadata-react-helmet="true"name="twitter:card"content="summary_large_image"><metadata-react-helmet="true"name="docusaurus_language"content="en"><metadata-react-helmet="true"name="docusaurus_version"content="current"><metadata-react-helmet="true"name="docusaurus_tag"content="docs-default-current"><metadata-react-helmet="true"property="og:title"content="Overview | OAuth2 Proxy"><metadata-react-helmet="true"name="description"content="oauth2-proxy can be configured via command line options, environment variables or config file (in decreasing order of precedence, i.e. command line options will overwrite environment variables and environment variables will overwrite configuration file settings)."><metadata-react-helmet="true"property="og:description"content="oauth2-proxy can be configured via command line options, environment variables or config file (in decreasing order of precedence, i.e. command line options will overwrite environment variables and environment variables will overwrite configuration file settings)."><metadata-react-helmet="true"property="og:url"content="https://oauth2-proxy.github.io/oauth2-proxy/docs/next/configuration/overview"><linkdata-react-helmet="true"rel="shortcut icon"href="/oauth2-proxy/img/logos/OAuth2_Proxy_icon.svg"><linkdata-react-helmet="true"rel="canonical"href="https://oauth2-proxy.github.io/oauth2-proxy/docs/next/configuration/overview"><linkrel="stylesheet"href="/oauth2-proxy/styles.b2862157.css">
and the <code>--email-domain</code> flag becomes <code>OAUTH2_PROXY_EMAIL_DOMAINS</code>.</p><h2><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="logging-configuration"></a>Logging Configuration<aaria-hidden="true"tabindex="-1"class="hash-link"href="#logging-configuration"title="Direct link to heading">#</a></h2><p>By default, OAuth2 Proxy logs all output to stdout. Logging can be configured to output to a rotating log file using the <code>--logging-filename</code> command.</p><p>If logging to a file you can also configure the maximum file size (<code>--logging-max-size</code>), age (<code>--logging-max-age</code>), max backup logs (<code>--logging-max-backups</code>), and if backup logs should be compressed (<code>--logging-compress</code>).</p><p>There are three different types of logging: standard, authentication, and HTTP requests. These can each be enabled or disabled with <code>--standard-logging</code>, <code>--auth-logging</code>, and <code>--request-logging</code>.</p><p>Each type of logging has its own configurable format and variables. By default these formats are similar to the Apache Combined Log.</p><p>Logging of requests to the <code>/ping</code> endpoint (or using <code>--ping-user-agent</code>) can be disabled with <code>--silence-ping-logging</code> reducing log volume. This flag appends the <code>--ping-path</code> to <code>--exclude-logging-paths</code>.</p><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="auth-log-format"></a>Auth Log Format<aaria-hidden="true"tabindex="-1"class="hash-link"href="#auth-log-format"title="Direct link to heading">#</a></h3><p>Authentication logs are logs which are guaranteed to contain a username or email address of a user attempting to authenticate. These logs are output by default in the below 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-undefined codeBlock_3iAC"><divclass="codeBlockLines_b7E3"style="color:#bfc7d5;background-color:#292d3e"><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"><REMOTE_ADDRESS> - <REQUEST ID> - <user@domain.com> [19/Mar/2015:17:20:19 -0400] [<STATUS>] <MESSAGE></span></div></div></div></div></div><p>The status block will contain one of the below strings:</p><ul><li><code>AuthSuccess</code> If a user has authenticated successfully by any method</li><li><code>AuthFailure</code> If the user failed to authenticate explicitly</li><li><code>AuthError</code> If there was an unexpected error during authentication</li></ul><p>If you require a different format than that, you can configure it with the <code>--auth-logging-format</code> flag.
The default format is configured as follows:</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-undefined codeBlock_3iAC"><divclass="codeBlockLines_b7E3"style="color:#bfc7d5;background-color:#292d3e"><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain">{{.Client}} - {{.RequestID}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}</span></div></div></div></div></div><p>Available variables for auth logging:</p><table><thead><tr><th>Variable</th><th>Example</th><th>Description</th></tr></thead><tbody><tr><td>Client</td><td>74.125.224.72</td><td>The client/remote IP address. Will use the X-Real-IP header it if exists & reverse-proxy is set to true.</td></tr><tr><td>Host</td><td>domain.com</td><td>The value of the Host header.</td></tr><tr><td>Message</td><td>Authenticated via OAuth2</td><td>The details of the auth attempt.</td></tr><tr><td>Protocol</td><td>HTTP/1.0</td><td>The request protocol.</td></tr><tr><td>RequestID</td><td>00010203-0405-4607-8809-0a0b0c0d0e0f</td><td>The request ID pulled from the <code>--request-id-header</code>. Random UUID if empty</td></tr><tr><td>RequestMethod</td><td>GET</td><td>The request method.</td></tr><tr><td>Timestamp</td><td>19/Mar/2015:17:20:19 -0400</td><td>The date and time of the logging event.</td></tr><tr><td>UserAgent</td><td>-</td><td>The full user agent as reported by the requesting client.</td></tr><tr><td>Username</td><td><ahref="mailto:username@email.com"target="_blank"rel="noopener noreferrer">username@email.com</a></td><td>The email or username of the auth request.</td></tr><tr><td>Status</td><td>AuthSuccess</td><td>The status of the auth request. See above for details.</td></tr></tbody></table><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="request-log-format"></a>Request Log Format<aaria-hidden="true"tabindex="-1"class="hash-link"href="#request-log-format"title="Direct link to heading">#</a></h3><p>HTTP request logs will output by default in the below 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-undefined codeBlock_3iAC"><divclass="codeBlockLines_b7E3"style="color:#bfc7d5;background-color:#292d3e"><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"><REMOTE_ADDRESS> - <REQUEST ID> - <user@domain.com> [19/Mar/2015:17:20:19 -0400] <HOST_HEADER> GET <UPSTREAM_HOST>"/path/" HTTP/1.1 "<USER_AGENT>"<RESPONSE_CODE><RESPONSE_BYTES><REQUEST_DURATION></span></div></div></div></div></div><p>If you require a different format than that, you can configure it with the <code>--request-logging-format</code> flag.
The default format is configured as follows:</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-undefined codeBlock_3iAC"><divclass="codeBlockLines_b7E3"style="color:#bfc7d5;background-color:#292d3e"><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain">{{.Client}} - {{.RequestID}} - {{.Username}} [{{.Timestamp}}] {{.Host}} {{.RequestMethod}} {{.Upstream}} {{.RequestURI}} {{.Protocol}} {{.UserAgent}} {{.StatusCode}} {{.ResponseSize}} {{.RequestDuration}}</span></div></div></div></div></div><p>Available variables for request logging:</p><table><thead><tr><th>Variable</th><th>Example</th><th>Description</th></tr></thead><tbody><tr><td>Client</td><td>74.125.224.72</td><td>The client/remote IP address. Will use the X-Real-IP header it if exists & reverse-proxy is set to true.</td></tr><tr><td>Host</td><td>domain.com</td><td>The value of the Host header.</td></tr><tr><td>Protocol</td><td>HTTP/1.0</td><td>The request protocol.</td></tr><tr><td>RequestDuration</td><td>0.001</td><td>The time in seconds that a request took to process.</td></tr><tr><td>RequestID</td><td>00010203-0405-4607-8809-0a0b0c0d0e0f</td><td>The request ID pulled from the <code>--request-id-header</code>. Random UUID if empty</td></tr><tr><td>RequestMethod</td><td>GET</td><td>The request method.</td></tr><tr><td>RequestURI</td><td>"/oauth2/auth"</td><td>The URI path of the request.</td></tr><tr><td>ResponseSize</td><td>12</td><td>The size in bytes of the response.</td></tr><tr><td>StatusCode</td><td>200</td><td>The HTTP status code of the response.</td></tr><tr><td>Timestamp</td><td>19/Mar/2015:17:20:19 -0400</td><td>The date and time of the logging event.</td></tr><tr><td>Upstream</td><td>-</td><td>The upstream data of the HTTP request.</td></tr><tr><td>UserAgent</td><td>-</td><td>The full user agent as reported by the requesting client.</td></tr><tr><td>Username</td><td><ahref="mailto:username@email.com"target="_blank"rel="noopener noreferrer">username@email.com</a></td><td>The email or username of the auth request.</td></tr></tbody></table><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="standard-log-format"></a>Standard Log Format<aaria-hidden="true"tabindex="-1"class="hash-link"href="#standard-log-format"title="Direct link to heading">#</a></h3><p>All other logging that is not covered by the above two types of logging will be output in this standard logging format. This includes configuration information at startup and errors that occur outside of a session. The default format is 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-undefined codeBlock_3iAC"><divclass="codeBlockLines_b7E3"style="color:#bfc7d5;background-color:#292d3e"><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain">[19/Mar/2015:17:20:19 -0400] [main.go:40] <MESSAGE></span></div></div></div></div></div><p>If you require a different format than that, you can configure it with the <code>--standard-logging-format</code> flag. The default format is configured as follows:</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-undefined codeBlock_3iAC"><divclass="codeBlockLines_b7E3"style="color:#bfc7d5;background-color:#292d3e"><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain">[{{.Timestamp}}] [{{.File}}] {{.Message}}</span></div></div></div></div></div><p>Available variables for standard logging:</p><table><thead><tr><th>Variable</th><th>Example</th><th>Description</th></tr></thead><tbody><tr><td>Timestamp</td><td>19/Mar/2015:17:20:19 -0400</td><td>The date and time of the logging event.</td></tr><tr
</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # pass information via X-User and X-Email headers to backend,</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # requires running with --set-xauthrequest flag</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> auth_request_set $user $upstream_http_x_auth_request_user;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> auth_request_set $email $upstream_http_x_auth_request_email;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> proxy_set_header X-User $user;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> proxy_set_header X-Email $email;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"style="display:inline-block">
</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # if you enabled --pass-access-token, this will pass the token to the backend</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> auth_request_set $token $upstream_http_x_auth_request_access_token;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> proxy_set_header X-Access-Token $token;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"style="display:inline-block">
</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # if you enabled --cookie-refresh, this is needed for it to work with auth_request</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> auth_request_set $auth_cookie $upstream_http_set_cookie;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> add_header Set-Cookie $auth_cookie;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"style="display:inline-block">
</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # limit and so the OAuth2 Proxy splits these into multiple parts.</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # so if your cookies are larger than 4kb, you will need to extract additional cookies manually.</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"style="display:inline-block">
</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # Extract the Cookie attributes from the first Set-Cookie header and append them</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # to the second part ($upstream_cookie_* variables only contain the raw cookie content)</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> if ($auth_cookie ~* "(; .*)") {</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> set $auth_cookie_name_0 $auth_cookie;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> }</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"style="display:inline-block">
</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # Send both Set-Cookie headers now if there was a second part</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> if ($auth_cookie_name_upstream_1) {</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> add_header Set-Cookie $auth_cookie_name_0;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> add_header Set-Cookie $auth_cookie_name_1;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> }</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"style="display:inline-block">
</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> proxy_pass http://backend/;</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> # or "root /path/to/site;" or "fastcgi_pass ..." etc</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> }</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain">}</span></div></div></div></div></div><p>When you use ingress-nginx in Kubernetes, you MUST use <code>kubernetes/ingress-nginx</code> (which includes the Lua module) and the following configuration snippet for your <code>Ingress</code>.
Variables set with <code>auth_request_set</code> are not <code>set</code>-able in plain nginx config when the location is processed via <code>proxy_pass</code> and then may only be processed by Lua.
</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> access_by_lua_block </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"> if ngx.var.name_upstream_1 ~= "" then</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> ngx.header</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">[</span><spanclass="token string"style="color:rgb(195, 232, 141)">"Set-Cookie"</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">]</span><spanclass="token plain"> = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain">match("(; .*)")</span></div><divclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> end</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>It is recommended to use <code>--session-store-type=redis</code> when expecting large sessions/OIDC tokens (<em>e.g.</em> with MS Azure).</p><p>You have to substitute <em>name</em> with the actual cookie name you configured via --cookie-name parameter. If you don't set a custom cookie name the variable should be "$upstream_cookie__oauth2_proxy_1" instead of "$upstream_cookie_name_1" and the new cookie-name should be "_oauth2_proxy_1=" instead of "name_1=".</p><h2><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="configuring-for-use-with-the-traefik-v2-forwardauth-middleware"></a>Configuring for use with the Traefik (v2) <code>ForwardAuth</code> middleware<aaria-hidden="true"tabindex="-1"class="hash-link"href="#configuring-for-use-with-the-traefik-v2-forwardauth-middleware"title="Direct link to heading">#</a></h2><p><strong>This option requires <code>--reverse-proxy</code> option to be set.</strong></p><h3><aaria-hidden="true"tabindex="-1"class="anchor enhancedAnchor_2cZh"id="forwardauth-with-401-errors-middleware"></a>ForwardAuth with 401 errors middleware<aaria-hidden="true"tabindex="-1"class="hash-link"href="#forwardauth-with-401-errors-middleware"title="Direct link to heading">#</a></h3><p>The <ahref="https://doc.traefik.io/traefik/middlewares/forwardauth/"target="_blank"rel="noopener noreferrer">Traefik v2 <code>ForwardAuth</code> middleware</a> allows Traefik to authenticate requests via the oauth2-proxy's <code>/oauth2/auth</code> endpoint on every request, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the whole request through. For example, on Dynamic File (YAML) Configuration:</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">http</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">routers</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">a-service</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">rule</span><spanclass="to
