Overview

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).

Generating a Cookie Secret

To generate a strong cookie secret use one of the below commands:

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

python -c 'import os,base64; print(base64.urlsafe_b64encode(os.urandom(32)).decode())'

dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64 | tr -d -- '\n' | tr -- '+/' '-_' ; echo

openssl rand -base64 32 | tr -- '+/' '-_'

# Add System.Web assembly to session, just in case
Add-Type -AssemblyName System.Web
[Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes([System.Web.Security.Membership]::GeneratePassword(32,4))).Replace("+","-").Replace("/","_")

# Valid 32 Byte Base64 URL encoding set that will decode to 24 []byte AES-192 secret
resource "random_password" "cookie_secret" {
  length           = 32
  override_special = "-_"
}

Config File

Every command line argument can be specified in a config file by replacing hyphens (-) with underscores (_). If the argument can be specified multiple times, the config option should be plural (trailing s).

An example oauth2-proxy.cfg config file is in the contrib directory. It can be used by specifying --config=/etc/oauth2-proxy.cfg

Config Options

Command Line Options

General Provider Options

Provider specific options can be found on their respective subpages.

Cookie Options

Header Options

Logging Options

Page Template Options

Probe Options

Proxy Options

Server Options

Session Options

Upstream Options

Upstreams Configuration

oauth2-proxy supports having multiple upstreams, and has the option to pass requests on to HTTP(S) servers, unix socket or serve static files from the file system.

To configure HTTP and HTTPS upstreams, provide such a URL in --upstream=URL. The scheme+host portion and the path portion are extracted to configure proxying behavior. When processing incoming requests, the path portion becomes a lookup key for selecting the destination server of the proxied request.

• Upstream URLs without a trailing slash, like in --upstream=http://service2.internal/foo, will match an incoming request exactly to /foo in https://this.o2p.example.com/foo, and forward the request on to service2.internal, but not match a request to https://this.o2p.example.com/foo/more nor ....com/food.
• Upstream URLs with a trailing slash, like in --upstream=http://service1.internal/foo/, will match any incoming request to any incoming requests's path starting with /foo/, like /foo/ and /foo/more and /foo/lots/more?etc.

If multiple --upstream URLs' paths match an incoming request, the one with the longest matching path (the most specific match) takes priority over shorter (less specific) ones.

Unix socket upstreams are configured as unix:///path/to/unix.sock.

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, e.g. file:///var/www/static/#/static/ will make /var/www/static/ available at http://[oauth2-proxy url]/static/.

Multiple upstreams can either be configured by supplying a comma separated list to the --upstream parameter, supplying the parameter multiple times or providing a list in the config file. When multiple upstreams are used routing to them will be based on the path they are set up with.

Environment variables

Every command line argument can be specified as an environment variable by prefixing it with OAUTH2_PROXY_, capitalising it, and replacing hyphens (-) with underscores (_). If the argument can be specified multiple times, the environment variable should be plural (trailing S).

This is particularly useful for storing secrets outside a configuration file or the command line.

For example, the --cookie-secret flag becomes OAUTH2_PROXY_COOKIE_SECRET. If a flag has the type string | list like the --email-domain flag it is available as an environment variable in plural form e.g. OAUTH2_PROXY_EMAIL_DOMAINS

Values for type string | list usually have a plural environment variable name and need to be seperated by , e.g. OAUTH2_PROXY_SKIP_AUTH_ROUTES="GET=^/api/status,POST=^/api/saved_objects/_import"

Please check the type for each config option first.

Logging Configuration

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.

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).

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.

Each type of logging has its own configurable format and variables. By default, these formats are similar to the Apache Combined Log.

Logging of requests to the /ping endpoint (or using --ping-user-agent) and the /ready endpoint can be disabled with --silence-ping-logging reducing log volume.

Auth Log Format

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:

<REMOTE_ADDRESS> - <REQUEST ID> - <[email protected]> [2015/03/19 17:20:19] [<STATUS>] <MESSAGE>

The status block will contain one of the below strings:

• AuthSuccess If a user has authenticated successfully by any method
• AuthFailure If the user failed to authenticate explicitly
• AuthError If there was an unexpected error during authentication

If you require a different format than that, you can configure it with the --auth-logging-format flag. The default format is configured as follows:

{{.Client}} - {{.RequestID}} - {{.Username}} [{{.Timestamp}}] [{{.Status}}] {{.Message}}

Available variables for auth logging:

Request Log Format

HTTP request logs will output by default in the below format:

<REMOTE_ADDRESS> - <REQUEST ID> - <[email protected]> [2015/03/19 17:20:19] <HOST_HEADER> GET <UPSTREAM_HOST> "/path/" HTTP/1.1 "<USER_AGENT>" <RESPONSE_CODE> <RESPONSE_BYTES> <REQUEST_DURATION>

If you require a different format than that, you can configure it with the --request-logging-format flag. The default format is configured as follows:

{{.Client}} - {{.RequestID}} - {{.Username}} [{{.Timestamp}}] {{.Host}} {{.RequestMethod}} {{.Upstream}} {{.RequestURI}} {{.Protocol}} {{.UserAgent}} {{.StatusCode}} {{.ResponseSize}} {{.RequestDuration}}

Available variables for request logging:

Standard Log Format

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:

[2015/03/19 17:20:19] [main.go:40] <MESSAGE>

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:

[{{.Timestamp}}] [{{.File}}] {{.Message}}

Available variables for standard logging: