<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 config file, command line options or environment variables."><metadata-react-helmet="true"property="og:description"content="oauth2-proxy can be configured via config file, command line options or environment variables."><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.58710d0f.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><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> - <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}} - {{.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>Protocol</td><td>HTTP/1.0</td><td>The request protocol.</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><tr><td>Message</td><td>Authenticated via OAuth2</td><td>The details of the auth attempt.</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> - <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}} - {{.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>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><td>File</td><td>main.go:40</td><td>The file and line number of the logging statement.</td></tr><tr><td>Message</td><td>HTTP: listening on 127.0.0.1:4180</td><td>The details of the l
</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><divclass="admonition admonition-note alert alert--secondary"><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="M6.3 5.69a.942.942 0 0 1-.28-.7c0-.28.09-.52.28-.7.19-.18.42-.28.7-.28.28 0 .52.09.7.28.18.19.28.42.28.7 0 .28-.09.52-.28.7a1 1 0 0 1-.7.3c-.28 0-.52-.11-.7-.3zM8 7.99c-.02-.25-.11-.48-.31-.69-.2-.19-.42-.3-.69-.31H6c-.27.02-.48.13-.69.31-.2.2-.3.44-.31.69h1v3c.02.27.11.5.31.69.2.2.42.31.69.31h1c.27 0 .48-.11.69-.31.2-.19.3-.42.31-.69H8V7.98v.01zM7 2.3c-3.14 0-5.7 2.54-5.7 5.68 0 3.14 2.56 5.7 5.7 5.7s5.7-2.55 5.7-5.7c0-3.15-2.56-5.69-5.7-5.69v.01zM7 .98c3.86 0 7 3.14 7 7s-3.14 7-7 7-7-3.12-7-7 3.14-7 7-7z"></path></svg></span>note</h5></div><divclass="admonition-content"><p>If you set up your OAuth2 provider to rotate your client secret, you can use the <code>client-secret-file</code> option to reload the secret when it is updated.</p></div></div></div></article><divclass="margin-vert--xl"><divclass="row"><divclass="col"><ahref="https://github.com/oauth2-proxy/oauth2-proxy/edit/master/docs/docs/configuration/overview.md"target="_blank"rel="noreferrer noopener"><svgfill="currentColor"height="1.2em"width="1.2em"preserveAspectRatio="xMidYMid meet"viewBox="0 0 40 40"style="margin-right:0.3em;vertical-align:sub"><g><pathd="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div></div></div><divclass="margin-vert--lg"><navclass="pagination-nav"aria-label="Blog list page navigation"><divclass="pagination-nav__item"><aclass="pagination-nav__link"href="/oauth2-proxy/docs/next/behaviour"><divclass="pagination-nav__sublabel">Previous</div><divclass="pagination-nav__label">« Behaviour</div></a></div><divclass="pagination-nav__item pagination-nav__item--next"><aclass="pagination-nav__link"href="/oauth2-proxy/docs/next/configuration/oauth_provider"><divclass="pagination-nav__sublabel">Next</div><divclass="pagination-nav__label">OAuth Provider Configuration »</div></a></div></nav></div></div></div><divclass="col col--3"><divclass="tableOfContents_3SO_"><ulclass="table-of-contents table-of-contents__left-border"><li><ahref="#config-file"class="table-o
