@@ -0,0 +1,306 @@
1+---
2+layout: default
3+title: Configuration
4+permalink: /configuration
5+nav_order: 3
6+---
7+
8+## Configuration
9+
10+`oauth2_proxy` can be configured via [config file](#config-file), [command line options](#command-line-options) or [environment variables](#environment-variables).
11+
12+To generate a strong cookie secret use `python -c 'import os,base64; print base64.urlsafe_b64encode(os.urandom(16))'`
13+
14+### Config File
15+
16+An example [oauth2_proxy.cfg](contrib/oauth2_proxy.cfg.example) config file is in the contrib directory. It can be used by specifying `-config=/etc/oauth2_proxy.cfg`
17+
18+### Command Line Options
19+
20+```
21+Usage of oauth2_proxy:
22+ -acr-values string: optional, used by login.gov (default "http://idmanagement.gov/ns/assurance/loa/1")
23+ -approval-prompt string: OAuth approval_prompt (default "force")
24+ -auth-logging: Log authentication attempts (default true)
25+ -auth-logging-format string: Template for authentication log lines (see "Logging Configuration" paragraph below)
26+ -authenticated-emails-file string: authenticate against emails via file (one per line)
27+ -azure-tenant string: go to a tenant-specific or common (tenant-independent) endpoint. (default "common")
28+ -basic-auth-password string: the password to set when passing the HTTP Basic Auth header
29+ -client-id string: the OAuth Client ID: ie: "123456.apps.googleusercontent.com"
30+ -client-secret string: the OAuth Client Secret
31+ -config string: path to config file
32+ -cookie-domain string: an optional cookie domain to force cookies to (ie: .yourcompany.com)
33+ -cookie-expire duration: expire timeframe for cookie (default 168h0m0s)
34+ -cookie-httponly: set HttpOnly cookie flag (default true)
35+ -cookie-name string: the name of the cookie that the oauth_proxy creates (default "_oauth2_proxy")
36+ -cookie-path string: an optional cookie path to force cookies to (ie: /poc/)* (default "/")
37+ -cookie-refresh duration: refresh the cookie after this duration; 0 to disable
38+ -cookie-secret string: the seed string for secure cookies (optionally base64 encoded)
39+ -cookie-secure: set secure (HTTPS) cookie flag (default true)
40+ -custom-templates-dir string: path to custom html templates
41+ -display-htpasswd-form: display username / password login form if an htpasswd file is provided (default true)
42+ -email-domain value: authenticate emails with the specified domain (may be given multiple times). Use * to authenticate any email
43+ -flush-interval: period between flushing response buffers when streaming responses (default "1s")
44+ -footer string: custom footer string. Use "-" to disable default footer.
45+ -gcp-healthchecks: will enable /liveness_check, /readiness_check, and / (with the proper user-agent) endpoints that will make it work well with GCP App Engine and GKE Ingresses (default false)
46+ -github-org string: restrict logins to members of this organisation
47+ -github-team string: restrict logins to members of any of these teams (slug), separated by a comma
48+ -google-admin-email string: the google admin to impersonate for api calls
49+ -google-group value: restrict logins to members of this google group (may be given multiple times).
50+ -google-service-account-json string: the path to the service account json credentials
51+ -htpasswd-file string: additionally authenticate against a htpasswd file. Entries must be created with "htpasswd -s" for SHA encryption
52+ -http-address string: [http://]<addr>:<port> or unix://<path> to listen on for HTTP clients (default "127.0.0.1:4180")
53+ -https-address string: <addr>:<port> to listen on for HTTPS clients (default ":443")
54+ -logging-compress: Should rotated log files be compressed using gzip (default false)
55+ -logging-filename string: File to log requests to, empty for stdout (default to stdout)
56+ -logging-local-time: If the time in log files and backup filenames are local or UTC time (default true)
57+ -logging-max-age int: Maximum number of days to retain old log files (default 7)
58+ -logging-max-backups int: Maximum number of old log files to retain; 0 to disable (default 0)
59+ -logging-max-size int: Maximum size in megabytes of the log file before rotation (default 100)
60+ -jwt-key string: private key in PEM format used to sign JWT, so that you can say something like -jwt-key="${OAUTH2_PROXY_JWT_KEY}": required by login.gov
61+ -jwt-key-file string: path to the private key file in PEM format used to sign the JWT so that you can say something like -jwt-key-file=/etc/ssl/private/jwt_signing_key.pem: required by login.gov
62+ -login-url string: Authentication endpoint
63+ -oidc-issuer-url: the OpenID Connect issuer URL. ie: "https://accounts.google.com"
64+ -oidc-jwks-url string: OIDC JWKS URI for token verification; required if OIDC discovery is disabled
65+ -pass-access-token: pass OAuth access_token to upstream via X-Forwarded-Access-Token header
66+ -pass-authorization-header: pass OIDC IDToken to upstream via Authorization Bearer header
67+ -pass-basic-auth: pass HTTP Basic Auth, X-Forwarded-User and X-Forwarded-Email information to upstream (default true)
68+ -pass-host-header: pass the request Host Header to upstream (default true)
69+ -pass-user-headers: pass X-Forwarded-User and X-Forwarded-Email information to upstream (default true)
70+ -profile-url string: Profile access endpoint
71+ -provider string: OAuth provider (default "google")
72+ -proxy-prefix string: the url root path that this proxy should be nested under (e.g. /<oauth2>/sign_in) (default "/oauth2")
73+ -proxy-websockets: enables WebSocket proxying (default true)
74+ -pubjwk-url string: JWK pubkey access endpoint: required by login.gov
75+ -redeem-url string: Token redemption endpoint
76+ -redirect-url string: the OAuth Redirect URL. ie: "https://internalapp.yourcompany.com/oauth2/callback"
77+ -request-logging: Log requests to stdout (default true)
78+ -request-logging-format: Template for request log lines (see "Logging Configuration" paragraph below)
79+ -resource string: The resource that is protected (Azure AD only)
80+ -scope string: OAuth scope specification
81+ -set-xauthrequest: set X-Auth-Request-User and X-Auth-Request-Email response headers (useful in Nginx auth_request mode)
82+ -set-authorization-header: set Authorization Bearer response header (useful in Nginx auth_request mode)
83+ -signature-key string: GAP-Signature request signature key (algorithm:secretkey)
84+ -skip-auth-preflight: will skip authentication for OPTIONS requests
85+ -skip-auth-regex value: bypass authentication for requests path's that match (may be given multiple times)
86+ -skip-oidc-discovery: bypass OIDC endpoint discovery. login-url, redeem-url and oidc-jwks-url must be configured in this case
87+ -skip-provider-button: will skip sign-in-page to directly reach the next step: oauth/start
88+ -ssl-insecure-skip-verify: skip validation of certificates presented when using HTTPS
89+ -standard-logging: Log standard runtime information (default true)
90+ -standard-logging-format string: Template for standard log lines (see "Logging Configuration" paragraph below)
91+ -tls-cert string: path to certificate file
92+ -tls-key string: path to private key file
93+ -upstream value: the http url(s) of the upstream endpoint or file:// paths for static files. Routing is based on the path
94+ -validate-url string: Access token validation endpoint
95+ -version: print version string
96+ -whitelist-domain: allowed domains for redirection after authentication. Prefix domain with a . to allow subdomains (eg .example.com)
97+```
98+
99+Note, when using the `whitelist-domain` option, any domain prefixed with a `.` will allow any subdomain of the specified domain as a valid redirect URL.
100+
101+See below for provider specific options
102+
103+### Upstreams Configuration
104+
105+`oauth2_proxy` supports having multiple upstreams, and has the option to pass requests on to HTTP(S) servers or serve static files from the file system. HTTP and HTTPS upstreams are configured by providing a URL such as `http://127.0.0.1:8080/` for the upstream parameter, that will forward all authenticated requests to be forwarded to the upstream server. If you instead provide `http://127.0.0.1:8080/some/path/` then it will only be requests that start with `/some/path/` which are forwarded to the upstream.
106+
107+Static file paths are configured as a file:// URL. `file:///var/www/static/` will serve the files from that directory at `http://[oauth2_proxy url]/var/www/static/`, which may not be what you want. You can provide the path to where the files should be available by adding a fragment to the configured URL. The value of the fragment will then be used to specify which path the files are available at. `file:///var/www/static/#/static/` will ie. make `/var/www/static/` available at `http://[oauth2_proxy url]/static/`.
108+
109+Multiple upstreams can either be configured by supplying a comma separated list to the `-upstream` parameter, supplying the parameter multiple times or provinding a list in the [config file](#config-file). When multiple upstreams are used routing to them will be based on the path they are set up with.
110+
111+### Environment variables
112+
113+The following environment variables can be used in place of the corresponding command-line arguments:
114+
115+- `OAUTH2_PROXY_CLIENT_ID`
116+- `OAUTH2_PROXY_CLIENT_SECRET`
117+- `OAUTH2_PROXY_COOKIE_NAME`
118+- `OAUTH2_PROXY_COOKIE_SECRET`
119+- `OAUTH2_PROXY_COOKIE_DOMAIN`
120+- `OAUTH2_PROXY_COOKIE_PATH`
121+- `OAUTH2_PROXY_COOKIE_EXPIRE`
122+- `OAUTH2_PROXY_COOKIE_REFRESH`
123+- `OAUTH2_PROXY_SIGNATURE_KEY`
124+
125+## Logging Configuration
126+
127+By default, OAuth2 Proxy logs all output to stdout. Logging can be configured to output to a rotating log file using the `-logging-filename` command.
128+
129+If logging to a file you can also configure the maximum file size (`-logging-max-size`), age (`-logging-max-age`), max backup logs (`-logging-max-backups`), and if backup logs should be compressed (`-logging-compress`).
130+
131+There are three different types of logging: standard, authentication, and HTTP requests. These can each be enabled or disabled with `-standard-logging`, `-auth-logging`, and `-request-logging`.
132+
133+Each type of logging has their own configurable format and variables. By default these formats are similar to the Apache Combined Log.
134+
135+### Auth Log Format
136+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:
137+
138+```
139+<REMOTE_ADDRESS> - <user@domain.com> [19/Mar/2015:17:20:19 -0400] [<STATUS>] <MESSAGE>
140+```
141+
142+The status block will contain one of the below strings:
143+
144+- `AuthSuccess` If a user has authenticated successfully by any method
145+- `AuthFailure` If the user failed to authenticate explicitly
146+- `AuthError` If there was an unexpected error during authentication
147+
148+If you require a different format than that, you can configure it with the `-auth-logging-format` flag.
149+The default format is configured as follows:
150+
151+```
152+{{.Client}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}
153+```
154+
155+Available variables for auth logging:
156+
157+| Variable | Example | Description |
158+| --- | --- | --- |
159+| Client | 74.125.224.72 | The client/remote IP address. Will use the X-Real-IP header it if exists. |
160+| Host | domain.com | The value of the Host header. |
161+| Protocol | HTTP/1.0 | The request protocol. |
162+| RequestMethod | GET | The request method. |
163+| Timestamp | 19/Mar/2015:17:20:19 -0400 | The date and time of the logging event. |
164+| UserAgent | - | The full user agent as reported by the requesting client. |
165+| Username | username@email.com | The email or username of the auth request. |
166+| Status | AuthSuccess | The status of the auth request. See above for details. |
167+| Message | Authenticated via OAuth2 | The details of the auth attempt. |
168+
169+### Request Log Format
170+HTTP request logs will output by default in the below format:
171+
172+```
173+<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>
174+```
175+
176+If you require a different format than that, you can configure it with the `-request-logging-format` flag.
177+The default format is configured as follows:
178+
179+```
180+{{.Client}} - {{.Username}} [{{.Timestamp}}] {{.Host}} {{.RequestMethod}} {{.Upstream}} {{.RequestURI}} {{.Protocol}} {{.UserAgent}} {{.StatusCode}} {{.ResponseSize}} {{.RequestDuration}}
181+```
182+
183+Available variables for request logging:
184+
185+| Variable | Example | Description |
186+| --- | --- | --- |
187+| Client | 74.125.224.72 | The client/remote IP address. Will use the X-Real-IP header it if exists. |
188+| Host | domain.com | The value of the Host header. |
189+| Protocol | HTTP/1.0 | The request protocol. |
190+| RequestDuration | 0.001 | The time in seconds that a request took to process. |
191+| RequestMethod | GET | The request method. |
192+| RequestURI | "/oauth2/auth" | The URI path of the request. |
193+| ResponseSize | 12 | The size in bytes of the response. |
194+| StatusCode | 200 | The HTTP status code of the response. |
195+| Timestamp | 19/Mar/2015:17:20:19 -0400 | The date and time of the logging event. |
196+| Upstream | - | The upstream data of the HTTP request. |
197+| UserAgent | - | The full user agent as reported by the requesting client. |
198+| Username | username@email.com | The email or username of the auth request. |
199+
200+### Standard Log Format
201+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:
202+
203+```
204+[19/Mar/2015:17:20:19 -0400] [main.go:40] <MESSAGE>
205+```
206+
207+If you require a different format than that, you can configure it with the `-standard-logging-format` flag. The default format is configured as follows:
208+
209+```
210+[{{.Timestamp}}] [{{.File}}] {{.Message}}
211+```
212+
213+Available variables for standard logging:
214+
215+| Variable | Example | Description |
216+| --- | --- | --- |
217+| Timestamp | 19/Mar/2015:17:20:19 -0400 | The date and time of the logging event. |
218+| File | main.go:40 | The file and line number of the logging statement. |
219+| Message | HTTP: listening on 127.0.0.1:4180 | The details of the log statement. |
220+
221+## <a name="nginx-auth-request"></a>Configuring for use with the Nginx `auth_request` directive
222+
223+The [Nginx `auth_request` directive](http://nginx.org/en/docs/http/ngx_http_auth_request_module.html) allows Nginx to authenticate requests via the oauth2_proxy's `/auth` endpoint, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the request through. For example:
224+
225+```nginx
226+server {
227+ listen 443 ssl;
228+ server_name ...;
229+ include ssl/ssl.conf;
230+
231+ location /oauth2/ {
232+ proxy_pass http://127.0.0.1:4180;
233+ proxy_set_header Host $host;
234+ proxy_set_header X-Real-IP $remote_addr;
235+ proxy_set_header X-Scheme $scheme;
236+ proxy_set_header X-Auth-Request-Redirect $request_uri;
237+ }
238+ location = /oauth2/auth {
239+ proxy_pass http://127.0.0.1:4180;
240+ proxy_set_header Host $host;
241+ proxy_set_header X-Real-IP $remote_addr;
242+ proxy_set_header X-Scheme $scheme;
243+ # nginx auth_request includes headers but not body
244+ proxy_set_header Content-Length "";
245+ proxy_pass_request_body off;
246+ }
247+
248+ location / {
249+ auth_request /oauth2/auth;
250+ error_page 401 = /oauth2/sign_in;
251+
252+ # pass information via X-User and X-Email headers to backend,
253+ # requires running with --set-xauthrequest flag
254+ auth_request_set $user $upstream_http_x_auth_request_user;
255+ auth_request_set $email $upstream_http_x_auth_request_email;
256+ proxy_set_header X-User $user;
257+ proxy_set_header X-Email $email;
258+
259+ # if you enabled --pass-access-token, this will pass the token to the backend
260+ auth_request_set $token $upstream_http_x_auth_request_access_token;
261+ proxy_set_header X-Access-Token $token;
262+
263+ # if you enabled --cookie-refresh, this is needed for it to work with auth_request
264+ auth_request_set $auth_cookie $upstream_http_set_cookie;
265+ add_header Set-Cookie $auth_cookie;
266+
267+ # When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb
268+ # limit and so the OAuth2 Proxy splits these into multiple parts.
269+ # Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,
270+ # so if your cookies are larger than 4kb, you will need to extract additional cookies manually.
271+ auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
272+
273+ # Extract the Cookie attributes from the first Set-Cookie header and append them
274+ # to the second part ($upstream_cookie_* variables only contain the raw cookie content)
275+ if ($auth_cookie ~* "(; .*)") {
276+ set $auth_cookie_name_0 $auth_cookie;
277+ set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
278+ }
279+
280+ # Send both Set-Cookie headers now if there was a second part
281+ if ($auth_cookie_name_upstream_1) {
282+ add_header Set-Cookie $auth_cookie_name_0;
283+ add_header Set-Cookie $auth_cookie_name_1;
284+ }
285+
286+ proxy_pass http://backend/;
287+ # or "root /path/to/site;" or "fastcgi_pass ..." etc
288+ }
289+}
290+```
291+
292+If you use ingress-nginx in Kubernetes (which includes the Lua module), you also can use the following configuration snippet for your Ingress:
293+
294+```yaml
295+nginx.ingress.kubernetes.io/auth-response-headers: Authorization
296+nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$request_uri
297+nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
298+nginx.ingress.kubernetes.io/configuration-snippet: |
299+ auth_request_set $name_upstream_1 $upstream_cookie_name_1;
300+
301+ access_by_lua_block {
302+ if ngx.var.name_upstream_1 ~= "" then
303+ ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
304+ end
305+ }
306+```