<titledata-rh="true">Overview | OAuth2 Proxy</title><metadata-rh="true"name="viewport"content="width=device-width,initial-scale=1"><metadata-rh="true"name="twitter:card"content="summary_large_image"><metadata-rh="true"property="og:url"content="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview"><metadata-rh="true"name="docusaurus_locale"content="en"><metadata-rh="true"name="docsearch:language"content="en"><metadata-rh="true"name="docusaurus_version"content="7.5.x"><metadata-rh="true"name="docusaurus_tag"content="docs-default-7.5.x"><metadata-rh="true"name="docsearch:version"content="7.5.x"><metadata-rh="true"name="docsearch:docusaurus_tag"content="docs-default-7.5.x"><metadata-rh="true"property="og:title"content="Overview | OAuth2 Proxy"><metadata-rh="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-rh="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-rh="true"rel="icon"href="/oauth2-proxy/img/logos/OAuth2_Proxy_icon.svg"><linkdata-rh="true"rel="canonical"href="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview"><linkdata-rh="true"rel="alternate"href="https://oauth2-proxy.github.io/oauth2-proxy/docs/configuration/overview"hreflang="en"><linkdata-rh="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.5c990d8a.css">
and the <code>--email-domain</code> flag becomes <code>OAUTH2_PROXY_EMAIL_DOMAINS</code>.</p><h2class="anchor anchorWithStickyNavbar_LWe7"id="logging-configuration">Logging Configuration<ahref="#logging-configuration"class="hash-link"aria-label="Direct link to Logging Configuration"title="Direct link to Logging Configuration"></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>) and the <code>/ready</code> endpoint can be disabled with <code>--silence-ping-logging</code> reducing log volume.</p><h3class="anchor anchorWithStickyNavbar_LWe7"id="auth-log-format">Auth Log Format<ahref="#auth-log-format"class="hash-link"aria-label="Direct link to Auth Log Format"title="Direct link to Auth Log Format"></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_Ckt0 theme-code-block"style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><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><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></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="codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><spanclass="token-line"style="color:#bfc7d5"><spanclass="token plain">{{.Client}} - {{.RequestID}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}</span><br></span></code></pre><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></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><h3class="anchor anchorWithStickyNavbar_LWe7"id="request-log-format">Request Log Format<ahref="#request-log-format"class="hash-link"aria-label="Direct link to Request Log Format"title="Direct link to Request Log Format"></a></h3><p>HTTP request logs will output by default in the below format:</p><divclass="codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><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><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></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="codeBlockContainer_Ckt0 theme-code-block"style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><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><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBox="0 0 24 24"class="copyButtonSuccessIcon_LjdS"><pathfill="currentColor"d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></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><h3class="anchor anchorWithStickyNavbar_LWe7"id="standard-log-format">Standard Log Format<ahref="#standard-log-format"class="hash-link"aria-label="Direct link to Standard Log Format"title="Direct link to Standard Log Format"></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_Ckt0 theme-code-block"style="--prism-color:#bfc7d5;--prism-background-color:#292d3e"><divclass="codeBlockContent_biex"><pretabindex="0"class="prism-code language-text codeBlock_bY9V thin-scrollbar"><codeclass="codeBlockLines_e6Vv"><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><divclass="buttonGroup__atx"><buttontype="button"aria-label="Copy code to clipboard"title="Copy"class="clean-btn"><spanclass="copyButtonIcons_eSgA"aria-hidden="true"><svgviewBox="0 0 24 24"class="copyButtonIcon_y97N"><pathfill="currentColor"d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svgviewBo
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.
