<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/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/configuration/overview"><linkdata-react-helmet="true"rel="alternate"href="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview"hreflang="en"><linkdata-react-helmet="true"rel="alternate"href="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview"hreflang="x-default"><linkrel="stylesheet"href="/oauth2-proxy/assets/css/styles.19258e03.css">
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.
