<titledata-react-helmet="true">Overview | OAuth2 Proxy</title><metadata-react-helmet="true"name="twitter:card"content="summary_large_image"><metadata-react-helmet="true"property="og:url"content="https://oauth2-proxy.github.io/oauth2-proxy/docs/7.2.x/configuration/overview"><metadata-react-helmet="true"name="docusaurus_locale"content="en"><metadata-react-helmet="true"name="docusaurus_version"content="7.2.x"><metadata-react-helmet="true"name="docusaurus_tag"content="docs-default-7.2.x"><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)."><linkdata-react-helmet="true"rel="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/7.2.x/configuration/overview"><linkdata-react-helmet="true"rel="alternate"href="https://oauth2-proxy.github.io/oauth2-proxy/docs/7.2.x/configuration/overview"hreflang="en"><linkdata-react-helmet="true"rel="alternate"href="https://oauth2-proxy.github.io/oauth2-proxy/docs/7.2.x/configuration/overview"hreflang="x-default"><linkrel="stylesheet"href="/oauth2-proxy/assets/css/styles.19258e03.css">
prefixing it with <code>OAUTH2_PROXY_</code>, capitalising it, and replacing hyphens (<code>-</code>)
with underscores (<code>_</code>). If the argument can be specified multiple times, the
environment variable should be plural (trailing <code>S</code>).</p><p>This is particularly useful for storing secrets outside of a configuration file
or the command line.</p><p>For example, the <code>--cookie-secret</code> flag becomes <code>OAUTH2_PROXY_COOKIE_SECRET</code>,
and the <code>--email-domain</code> flag becomes <code>OAUTH2_PROXY_EMAIL_DOMAINS</code>.</p><h2class="anchor anchorWithStickyNavbar_mojV"id="logging-configuration">Logging Configuration<aclass="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><h3class="anchor anchorWithStickyNavbar_mojV"id="auth-log-format">Auth Log Format<aclass="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="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"><REMOTE_ADDRESS> - <REQUEST ID> - <user@domain.com> [19/Mar/2015:17:20:19 -0400] [<STATUS>] <MESSAGE></span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></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="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">{{.Client}} - {{.RequestID}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></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><h3class="anchor anchorWithStickyNavbar_mojV"id="request-log-format">Request Log Format<aclass="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="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"><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><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></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="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">{{.Client}} - {{.RequestID}} - {{.Username}} [{{.Timestamp}}] {{.Host}} {{.RequestMethod}} {{.Upstream}} {{.RequestURI}} {{.Protocol}} {{.UserAgent}} {{.StatusCode}} {{.ResponseSize}} {{.RequestDuration}}</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></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><h3class="anchor anchorWithStickyNavbar_mojV"id="standard-log-format">Standard Log Format<aclass="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="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">[19/Mar/2015:17:20:19 -0400] [main.go:40] <MESSAGE></span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></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="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">[{{.Timestamp}}] [{{.File}}] {{.Message}}</span><br></span></code></pre><buttontype="button"aria-label="Copy code to clipboard"class="copyButton_wuS7 clean-btn">Copy</button></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><
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.
Note that <code>nginxinc/kubernetes-ingress</code> does not include the Lua module.</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">nginx.ingress.kubernetes.io/auth-response-headers</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain"> Authorization</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token key atrule">nginx.ingress.kubernetes.io/auth-signin</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain"> https</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain">//$host/oauth2/start</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">?</span><spanclass="token plain">rd=$escaped_request_uri</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token key atrule">nginx.ingress.kubernetes.io/auth-url</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain"> https</span><spanclass="token punctuation"style="color:rgb(199, 146, 234)">:</span><spanclass="token plain">//$host/oauth2/auth</span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"></span><spanclass="token key atrule">nginx.ingress.kubernetes.io/configuration-snippet</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 scalar string"style="color:rgb(195, 232, 141)"></span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token scalar string"style="color:rgb(195, 232, 141)"> auth_request_set $name_upstream_1 $upstream_cookie_name_1;</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"style="display:inline-block"></span><br></span><spanclass="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><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> if ngx.var.name_upstream_1 ~= "" then</span><br></span><spanclass="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><spanclass="token important">*)")</span><spanclass="token plain"></span><br></span><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain"> end</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>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_pr
