mirror of
https://github.com/oauth2-proxy/oauth2-proxy.git
synced 2025-05-19 22:23:30 +02:00
docs: restructure all options and flags (#2747)
* remove package lock file * update next docs * update latest v7.6 docs * switch to npm install for docs * sort sections alphabetically
This commit is contained in:
Jan Larwig
GitHub
parent
95cbd0cdfb
commit
9a9e7b7a37
6
.github/workflows/docs.yaml
vendored
6
.github/workflows/docs.yaml
vendored
@ -24,13 +24,11 @@ jobs:
|
||||
with:
|
||||
# renovate: datasource=node-version depName=node
|
||||
node-version: 20
|
||||
cache: npm
|
||||
cache-dependency-path: "./docs/package-lock.json"
|
||||
|
||||
- name: Test Build
|
||||
working-directory: ./docs
|
||||
run: |
|
||||
npm ci
|
||||
npm install
|
||||
npm run build
|
||||
|
||||
build-docs:
|
||||
@ -47,7 +45,7 @@ jobs:
|
||||
- name: Build docusaurus
|
||||
working-directory: ./docs
|
||||
run: |
|
||||
npm ci
|
||||
npm install
|
||||
npm run build
|
||||
|
||||
- name: Upload artifact
|
||||
|
||||
3
docs/.gitignore
vendored
3
docs/.gitignore
vendored
@ -1,5 +1,8 @@
|
||||
# Dependencies
|
||||
/node_modules
|
||||
package-lock.json
|
||||
pnpm-lock.yaml
|
||||
yarn.lock
|
||||
|
||||
# Production
|
||||
/build
|
||||
|
||||
270
docs/docs/configuration/integration.md
Normal file
270
docs/docs/configuration/integration.md
Normal file
@ -0,0 +1,270 @@
|
||||
---
|
||||
id: integration
|
||||
title: Integration
|
||||
---
|
||||
|
||||
## Configuring for use with the Nginx `auth_request` directive
|
||||
|
||||
**This option requires `--reverse-proxy` option to be set.**
|
||||
|
||||
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:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name ...;
|
||||
include ssl/ssl.conf;
|
||||
|
||||
location /oauth2/ {
|
||||
proxy_pass http://127.0.0.1:4180;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Auth-Request-Redirect $request_uri;
|
||||
# or, if you are handling multiple domains:
|
||||
# proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri;
|
||||
}
|
||||
location = /oauth2/auth {
|
||||
proxy_pass http://127.0.0.1:4180;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-Uri $request_uri;
|
||||
# nginx auth_request includes headers but not body
|
||||
proxy_set_header Content-Length "";
|
||||
proxy_pass_request_body off;
|
||||
}
|
||||
|
||||
location / {
|
||||
auth_request /oauth2/auth;
|
||||
error_page 401 =403 /oauth2/sign_in;
|
||||
|
||||
# pass information via X-User and X-Email headers to backend,
|
||||
# requires running with --set-xauthrequest flag
|
||||
auth_request_set $user $upstream_http_x_auth_request_user;
|
||||
auth_request_set $email $upstream_http_x_auth_request_email;
|
||||
proxy_set_header X-User $user;
|
||||
proxy_set_header X-Email $email;
|
||||
|
||||
# if you enabled --pass-access-token, this will pass the token to the backend
|
||||
auth_request_set $token $upstream_http_x_auth_request_access_token;
|
||||
proxy_set_header X-Access-Token $token;
|
||||
|
||||
# if you enabled --cookie-refresh, this is needed for it to work with auth_request
|
||||
auth_request_set $auth_cookie $upstream_http_set_cookie;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
|
||||
# When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb
|
||||
# limit and so the OAuth2 Proxy splits these into multiple parts.
|
||||
# Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,
|
||||
# so if your cookies are larger than 4kb, you will need to extract additional cookies manually.
|
||||
auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
|
||||
|
||||
# Extract the Cookie attributes from the first Set-Cookie header and append them
|
||||
# to the second part ($upstream_cookie_* variables only contain the raw cookie content)
|
||||
if ($auth_cookie ~* "(; .*)") {
|
||||
set $auth_cookie_name_0 $auth_cookie;
|
||||
set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
|
||||
}
|
||||
|
||||
# Send both Set-Cookie headers now if there was a second part
|
||||
if ($auth_cookie_name_upstream_1) {
|
||||
add_header Set-Cookie $auth_cookie_name_0;
|
||||
add_header Set-Cookie $auth_cookie_name_1;
|
||||
}
|
||||
|
||||
proxy_pass http://backend/;
|
||||
# or "root /path/to/site;" or "fastcgi_pass ..." etc
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When you use ingress-nginx in Kubernetes, you MUST use `kubernetes/ingress-nginx` (which includes the Lua module) and the following configuration snippet for your `Ingress`.
|
||||
Variables set with `auth_request_set` are not `set`-able in plain nginx config when the location is processed via `proxy_pass` and then may only be processed by Lua.
|
||||
Note that `nginxinc/kubernetes-ingress` does not include the Lua module.
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/auth-response-headers: Authorization
|
||||
nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$escaped_request_uri
|
||||
nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
|
||||
nginx.ingress.kubernetes.io/configuration-snippet: |
|
||||
auth_request_set $name_upstream_1 $upstream_cookie_name_1;
|
||||
|
||||
access_by_lua_block {
|
||||
if ngx.var.name_upstream_1 ~= "" then
|
||||
ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
|
||||
end
|
||||
}
|
||||
```
|
||||
It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
|
||||
|
||||
You have to substitute *name* 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=".
|
||||
|
||||
## Configuring for use with the Traefik (v2) `ForwardAuth` middleware
|
||||
|
||||
**This option requires `--reverse-proxy` option to be set.**
|
||||
|
||||
## ForwardAuth with 401 errors middleware
|
||||
|
||||
The [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) allows Traefik to authenticate requests via the oauth2-proxy's `/oauth2/auth` endpoint on every request, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the whole request through. For example, on Dynamic File (YAML) Configuration:
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
a-service:
|
||||
rule: "Host(`a-service.example.com`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-errors
|
||||
- oauth-auth
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
oauth:
|
||||
rule: "Host(`a-service.example.com`, `oauth.example.com`) && PathPrefix(`/oauth2/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
|
||||
services:
|
||||
a-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.2:7555
|
||||
oauth-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.1:4180
|
||||
|
||||
middlewares:
|
||||
auth-headers:
|
||||
headers:
|
||||
sslRedirect: true
|
||||
stsSeconds: 315360000
|
||||
browserXssFilter: true
|
||||
contentTypeNosniff: true
|
||||
forceSTSHeader: true
|
||||
sslHost: example.com
|
||||
stsIncludeSubdomains: true
|
||||
stsPreload: true
|
||||
frameDeny: true
|
||||
oauth-auth:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/oauth2/auth
|
||||
trustForwardHeader: true
|
||||
oauth-errors:
|
||||
errors:
|
||||
status:
|
||||
- "401-403"
|
||||
service: oauth-backend
|
||||
query: "/oauth2/sign_in?rd={url}"
|
||||
```
|
||||
|
||||
## ForwardAuth with static upstreams configuration
|
||||
|
||||
Redirect to sign_in functionality provided without the use of `errors` middleware with [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) pointing to oauth2-proxy service's `/` endpoint
|
||||
|
||||
**Following options need to be set on `oauth2-proxy`:**
|
||||
- `--upstream=static://202`: Configures a static response for authenticated sessions
|
||||
- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
a-service-route-1:
|
||||
rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-auth-redirect # redirects all unauthenticated to oauth2 signin
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
a-service-route-2:
|
||||
rule: "Host(`a-service.example.com`) && PathPrefix(`/no-auto-redirect`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-auth-wo-redirect # unauthenticated session will return a 401
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
services-oauth2-route:
|
||||
rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/oauth2/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
oauth2-proxy-route:
|
||||
rule: "Host(`oauth.example.com`) && PathPrefix(`/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
|
||||
services:
|
||||
a-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.2:7555
|
||||
b-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.3:7555
|
||||
oauth-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.1:4180
|
||||
|
||||
middlewares:
|
||||
auth-headers:
|
||||
headers:
|
||||
sslRedirect: true
|
||||
stsSeconds: 315360000
|
||||
browserXssFilter: true
|
||||
contentTypeNosniff: true
|
||||
forceSTSHeader: true
|
||||
sslHost: example.com
|
||||
stsIncludeSubdomains: true
|
||||
stsPreload: true
|
||||
frameDeny: true
|
||||
oauth-auth-redirect:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/
|
||||
trustForwardHeader: true
|
||||
authResponseHeaders:
|
||||
- X-Auth-Request-Access-Token
|
||||
- Authorization
|
||||
oauth-auth-wo-redirect:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/oauth2/auth
|
||||
trustForwardHeader: true
|
||||
authResponseHeaders:
|
||||
- X-Auth-Request-Access-Token
|
||||
- Authorization
|
||||
```
|
||||
|
||||
:::note
|
||||
If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
|
||||
:::
|
||||
@ -5,7 +5,7 @@ title: Overview
|
||||
|
||||
`oauth2-proxy` can be configured via [command line options](#command-line-options), [environment variables](#environment-variables) or [config file](#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
|
||||
## Generating a Cookie Secret
|
||||
|
||||
To generate a strong cookie secret use one of the below commands:
|
||||
|
||||
@ -56,167 +56,208 @@ import TabItem from '@theme/TabItem';
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Config File
|
||||
## 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](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/contrib/oauth2-proxy.cfg.example) config file is in the contrib directory. It can be used by specifying `--config=/etc/oauth2-proxy.cfg`
|
||||
|
||||
## Config Options
|
||||
|
||||
### Command Line Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ---------------------------------------------- | -------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| `--acr-values` | `acr_values` | string | optional, see [docs](https://openid.net/specs/openid-connect-eap-acr-values-1_0.html#acrValues) | `""` |
|
||||
| `--allow-query-semicolons` | `allow_query_semicolons` | bool | allow the use of semicolons in query args ([required for some legacy applications](https://github.com/golang/go/issues/25192)) | `false` |
|
||||
| `--api-route` | `api_routes` | string \| list | return HTTP 401 instead of redirecting to authentication server if token is not valid. Format: path_regex | |
|
||||
| `--approval-prompt` | `approval_prompt` | string | OAuth approval_prompt | `"force"` |
|
||||
| `--auth-logging` | `auth_logging` | bool | Log authentication attempts | true |
|
||||
| `--auth-logging-format` | `auth_logging_format` | string | Template for authentication log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| `--authenticated-emails-file` | `authenticated_emails_file` | string | authenticate against emails via file (one per line) | |
|
||||
| `--azure-tenant` | `azure_tenant` | string | go to a tenant-specific or common (tenant-independent) endpoint. | `"common"` |
|
||||
| `--backend-logout-url` | `backend_logout_url` | string | URL to perform backend logout, if you use `{id_token}` in the url it will be replaced by the actual `id_token` of the user session | |
|
||||
| `--basic-auth-password` | `basic_auth_password` | string | the password to set when passing the HTTP Basic Auth header | |
|
||||
| `--client-id` | `client_id` | string | the OAuth Client ID, e.g. `"123456.apps.googleusercontent.com"` | |
|
||||
| `--client-secret` | `client_secret` | string | the OAuth Client Secret | |
|
||||
| `--client-secret-file` | `client_secret_file` | string | the file with OAuth Client Secret | |
|
||||
| `--code-challenge-method` | `code_challenge_method` | string | use PKCE code challenges with the specified method. Either 'plain' or 'S256' (recommended) | |
|
||||
| `--config` | --- | string | path to config file | |
|
||||
| `--cookie-domain` | `cookie_domains` | string \| list | Optional cookie domains to force cookies to (e.g. `.yourcompany.com`). The longest domain matching the request's host will be used (or the shortest cookie domain if there is no match). | |
|
||||
| `--cookie-expire` | `cookie_expire` | duration | expire timeframe for cookie. If set to 0, cookie becomes a session-cookie which will expire when the browser is closed. | 168h0m0s |
|
||||
| `--cookie-httponly` | `cookie_httponly` | bool | set HttpOnly cookie flag | true |
|
||||
| `--cookie-name` | `cookie_name` | string | the name of the cookie that the oauth_proxy creates. Should be changed to use a [cookie prefix](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes) (`__Host-` or `__Secure-`) if `--cookie-secure` is set. | `"_oauth2_proxy"` |
|
||||
| `--cookie-path` | `cookie_path` | string | an optional cookie path to force cookies to (e.g. `/poc/`) | `"/"` |
|
||||
| `--cookie-refresh` | `cookie_refresh` | duration | refresh the cookie after this duration; `0` to disable; not supported by all providers [^1] | |
|
||||
| `--cookie-secret` | `cookie_secret` | string | the seed string for secure cookies (optionally base64 encoded) | |
|
||||
| `--cookie-secure` | `cookie_secure` | bool | set [secure (HTTPS only) cookie flag](https://owasp.org/www-community/controls/SecureFlag) | true |
|
||||
| `--cookie-samesite` | `cookie_samesite` | string | set SameSite cookie attribute (`"lax"`, `"strict"`, `"none"`, or `""`). | `""` |
|
||||
| `--cookie-csrf-per-request` | `cookie_csrf_per_request` | bool | Enable having different CSRF cookies per request, making it possible to have parallel requests. | false |
|
||||
| `--cookie-csrf-expire` | `cookie_csrf_expire` | duration | expire timeframe for CSRF cookie | 15m |
|
||||
| `--custom-templates-dir` | `custom_templates_dir` | string | path to custom html templates | |
|
||||
| `--custom-sign-in-logo` | `custom_sign_in_logo` | string | path or a URL to an custom image for the sign_in page logo. Use `"-"` to disable default logo. |
|
||||
| `--display-htpasswd-form` | `display_htpasswd_form` | bool | display username / password login form if an htpasswd file is provided | true |
|
||||
| `--email-domain` | `email_domains` | string \| list | authenticate emails with the specified domain (may be given multiple times). Use `*` to authenticate any email | |
|
||||
| `--errors-to-info-log` | `errors_to_info_log` | bool | redirects error-level logging to default log channel instead of stderr | false |
|
||||
| `--extra-jwt-issuers` | `extra_jwt_issuers` | string | if `--skip-jwt-bearer-tokens` is set, a list of extra JWT `issuer=audience` (see a token's `iss`, `aud` fields) pairs (where the issuer URL has a `.well-known/openid-configuration` or a `.well-known/jwks.json`) | |
|
||||
| `--exclude-logging-path` | `exclude_logging_paths` | string | comma separated list of paths to exclude from logging, e.g. `"/ping,/path2"` | `""` (no paths excluded) |
|
||||
| `--flush-interval` | `flush_interval` | duration | period between flushing response buffers when streaming responses | `"1s"` |
|
||||
| `--force-https` | `force_https` | bool | enforce https redirect | `false` |
|
||||
| `--force-json-errors` | `force_json_errors` | bool | force JSON errors instead of HTTP error pages or redirects | `false` |
|
||||
| `--banner` | `banner` | string | custom (html) banner string. Use `"-"` to disable default banner. | |
|
||||
| `--footer` | `footer` | string | custom (html) footer string. Use `"-"` to disable default footer. | |
|
||||
| `--github-org` | `github_org` | string | restrict logins to members of this organisation | |
|
||||
| `--github-team` | `github_team` | string | restrict logins to members of any of these teams (slug), separated by a comma | |
|
||||
| `--github-repo` | `github_repo` | string | restrict logins to collaborators of this repository formatted as `orgname/repo` | |
|
||||
| `--github-token` | `github_token` | string | the token to use when verifying repository collaborators (must have push access to the repository) | |
|
||||
| `--github-user` | `github_users` | string \| list | To allow users to login by username even if they do not belong to the specified org and team or collaborators | |
|
||||
| `--gitlab-group` | `gitlab_groups` | string \| list | restrict logins to members of any of these groups (slug), separated by a comma | |
|
||||
| `--gitlab-projects` | `gitlab_projects` | string \| list | restrict logins to members of any of these projects (may be given multiple times) formatted as `orgname/repo=accesslevel`. Access level should be a value matching [Gitlab access levels](https://docs.gitlab.com/ee/api/members.html#valid-access-levels), defaulted to 20 if absent | |
|
||||
| `--google-admin-email` | `google_admin_email` | string | the google admin to impersonate for api calls | |
|
||||
| `--google-group` | `google_groups` | string | restrict logins to members of this google group (may be given multiple times). | |
|
||||
| `--google-service-account-json` | `google_service_account_json` | string | the path to the service account json credentials | |
|
||||
| `--google-use-application-default-credentials` | `google_use_application_default_credentials` | bool | use application default credentials instead of service account json (i.e. GKE Workload Identity) | |
|
||||
| `--google-target-principal` | `google_target_principal` | bool | the target principal to impersonate when using ADC | defaults to the service account configured for ADC |
|
||||
| `--htpasswd-file` | `htpasswd_file` | string | additionally authenticate against a htpasswd file. Entries must be created with `htpasswd -B` for bcrypt encryption | |
|
||||
| `--htpasswd-user-group` | `htpasswd_user_groups` | string \| list | the groups to be set on sessions for htpasswd users | |
|
||||
| `--http-address` | `http_address` | string | `[http://]<addr>:<port>` or `unix://<path>` to listen on for HTTP clients. Square brackets are required for ipv6 address, e.g. `http://[::1]:4180` | `"127.0.0.1:4180"` |
|
||||
| `--https-address` | `https_address` | string | `[https://]<addr>:<port>` to listen on for HTTPS clients. Square brackets are required for ipv6 address, e.g. `https://[::1]:443` | `":443"` |
|
||||
| `--logging-compress` | `logging_compress` | bool | Should rotated log files be compressed using gzip | false |
|
||||
| `--logging-filename` | `logging_filename` | string | File to log requests to, empty for `stdout` | `""` (stdout) |
|
||||
| `--logging-local-time` | `logging_local_time` | bool | Use local time in log files and backup filenames instead of UTC | true (local time) |
|
||||
| `--logging-max-age` | `logging_max_age` | int | Maximum number of days to retain old log files | 7 |
|
||||
| `--logging-max-backups` | `logging_max_backups` | int | Maximum number of old log files to retain; 0 to disable | 0 |
|
||||
| `--logging-max-size` | `logging_max_size` | int | Maximum size in megabytes of the log file before rotation | 100 |
|
||||
| `--jwt-key` | `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 | |
|
||||
| `--jwt-key-file` | `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 | |
|
||||
| `--login-url` | `login_url` | string | Authentication endpoint | |
|
||||
| `--insecure-oidc-allow-unverified-email` | `insecure_oidc_allow_unverified_email` | bool | don't fail if an email address in an id_token is not verified | false |
|
||||
| `--insecure-oidc-skip-issuer-verification` | `insecure_oidc_skip_issuer_verification` | bool | allow the OIDC issuer URL to differ from the expected (currently required for Azure multi-tenant compatibility) | false |
|
||||
| `--insecure-oidc-skip-nonce` | `insecure_oidc_skip_nonce` | bool | skip verifying the OIDC ID Token's nonce claim | true |
|
||||
| `--oidc-issuer-url` | `oidc_issuer_url` | string | the OpenID Connect issuer URL, e.g. `"https://accounts.google.com"` | |
|
||||
| `--oidc-jwks-url` | `oidc_jwks_url` | string | OIDC JWKS URI for token verification; required if OIDC discovery is disabled | |
|
||||
| `--oidc-email-claim` | `oidc_email_claim` | string | which OIDC claim contains the user's email | `"email"` |
|
||||
| `--oidc-groups-claim` | `oidc_groups_claim` | string | which OIDC claim contains the user groups | `"groups"` |
|
||||
| `--oidc-audience-claim` | `oidc_audience_claims` | string | which OIDC claim contains the audience | `"aud"` |
|
||||
| `--oidc-extra-audience` | `oidc_extra_audiences` | string \| list | additional audiences which are allowed to pass verification | `"[]"` |
|
||||
| `--pass-access-token` | `pass_access_token` | bool | pass OAuth access_token to upstream via X-Forwarded-Access-Token header. When used with `--set-xauthrequest` this adds the X-Auth-Request-Access-Token header to the response | false |
|
||||
| `--pass-authorization-header` | `pass_authorization_header` | bool | pass OIDC IDToken to upstream via Authorization Bearer header | false |
|
||||
| `--pass-basic-auth` | `pass_basic_auth` | bool | pass HTTP Basic Auth, X-Forwarded-User, X-Forwarded-Email and X-Forwarded-Preferred-Username information to upstream | true |
|
||||
| `--prefer-email-to-user` | `prefer_email_to_user` | bool | Prefer to use the Email address as the Username when passing information to upstream. Will only use Username if Email is unavailable, e.g. htaccess authentication. Used in conjunction with `--pass-basic-auth` and `--pass-user-headers` | false |
|
||||
| `--pass-host-header` | `pass_host_header` | bool | pass the request Host Header to upstream | true |
|
||||
| `--pass-user-headers` | `pass_user_headers` | bool | pass X-Forwarded-User, X-Forwarded-Groups, X-Forwarded-Email and X-Forwarded-Preferred-Username information to upstream | true |
|
||||
| `--profile-url` | `profile_url` | string | Profile access endpoint | |
|
||||
| `--skip-claims-from-profile-url` | `skip_claims_from_profile_url` | bool | skip request to Profile URL for resolving claims not present in id_token | false |
|
||||
| `--prompt` | `prompt` | string | [OIDC prompt](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest); if present, `approval-prompt` is ignored | `""` |
|
||||
| `--provider` | `provider` | string | OAuth provider | google |
|
||||
| `--provider-ca-file` | `provider_ca_file` | string \| list | Paths to CA certificates that should be used when connecting to the provider. If not specified, the default Go trust sources are used instead. |
|
||||
| `--use-system-trust-store` | `use_system_trust_store` | bool | Determines if `provider-ca-file` files and the system trust store are used. If set to true, your custom CA files and the system trust store are used otherwise only your custom CA files. | false |
|
||||
| `--provider-display-name` | `provider_display_name` | string | Override the provider's name with the given string; used for the sign-in page | (depends on provider) |
|
||||
| `--ping-path` | `ping_path` | string | the ping endpoint that can be used for basic health checks | `"/ping"` |
|
||||
| `--ping-user-agent` | `ping_user_agent` | string | a User-Agent that can be used for basic health checks | `""` (don't check user agent) |
|
||||
| `--ready-path` | `ready_path` | string | the ready endpoint that can be used for deep health checks | `"/ready"` |
|
||||
| `--metrics-address` | `metrics_address` | string | the address prometheus metrics will be scraped from | `""` |
|
||||
| `--proxy-prefix` | `proxy_prefix` | string | the url root path that this proxy should be nested under (e.g. /`<oauth2>/sign_in`) | `"/oauth2"` |
|
||||
| `--proxy-websockets` | `proxy_websockets` | bool | enables WebSocket proxying | true |
|
||||
| `--pubjwk-url` | `pubjwk_url` | string | JWK pubkey access endpoint: required by login.gov | |
|
||||
| `--real-client-ip-header` | `real_client_ip_header` | string | Header used to determine the real IP of the client, requires `--reverse-proxy` to be set (one of: X-Forwarded-For, X-Real-IP, or X-ProxyUser-IP) | X-Real-IP |
|
||||
| `--redeem-url` | `redeem_url` | string | Token redemption endpoint | |
|
||||
| `--redirect-url` | `redirect_url` | string | the OAuth Redirect URL, e.g. `"https://internalapp.yourcompany.com/oauth2/callback"` | |
|
||||
| `--relative-redirect-url` | `relative_redirect_url` | bool | allow relative OAuth Redirect URL.` | false |
|
||||
| `--redis-cluster-connection-urls` | `redis_cluster_connection_urls` | string \| list | List of Redis cluster connection URLs (e.g. `redis://HOST[:PORT]`). Used in conjunction with `--redis-use-cluster` | |
|
||||
| `--redis-connection-url` | `redis_connection_url` | string | URL of redis server for redis session storage (e.g. `redis://HOST[:PORT]`) | |
|
||||
| `--redis-insecure-skip-tls-verify` | `redis_insecure_skip_tls_verify` | bool | skip TLS verification when connecting to Redis | false |
|
||||
| `--redis-password` | `redis_password` | string | Redis password. Applicable for all Redis configurations. Will override any password set in `--redis-connection-url` | |
|
||||
| `--redis-sentinel-password` | `redis_sentinel_password` | string | Redis sentinel password. Used only for sentinel connection; any redis node passwords need to use `--redis-password` | |
|
||||
| `--redis-sentinel-master-name` | `redis_sentinel_master_name` | string | Redis sentinel master name. Used in conjunction with `--redis-use-sentinel` | |
|
||||
| `--redis-sentinel-connection-urls` | `redis_sentinel_connection_urls` | string \| list | List of Redis sentinel connection URLs (e.g. `redis://HOST[:PORT]`). Used in conjunction with `--redis-use-sentinel` | |
|
||||
| `--redis-use-cluster` | `redis_use_cluster` | bool | Connect to redis cluster. Must set `--redis-cluster-connection-urls` to use this feature | false |
|
||||
| `--redis-use-sentinel` | `redis_use_sentinel` | bool | Connect to redis via sentinels. Must set `--redis-sentinel-master-name` and `--redis-sentinel-connection-urls` to use this feature | false |
|
||||
| `--redis-connection-idle-timeout` | `redis_connection_idle_timeout` | int | Redis connection idle timeout seconds. If Redis [timeout](https://redis.io/docs/reference/clients/#client-timeouts) option is set to non-zero, the `--redis-connection-idle-timeout` must be less than Redis timeout option. Example: if either redis.conf includes `timeout 15` or using `CONFIG SET timeout 15` the `--redis-connection-idle-timeout` must be at least `--redis-connection-idle-timeout=14` | 0 |
|
||||
| `--request-id-header` | `request_id_header` | string | Request header to use as the request ID in logging | X-Request-Id |
|
||||
| `--request-logging` | `request_logging` | bool | Log requests | true |
|
||||
| `--request-logging-format` | `request_logging_format` | string | Template for request log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| `--resource` | `resource` | string | The resource that is protected (Azure AD only) | |
|
||||
| `--reverse-proxy` | `reverse_proxy` | bool | are we running behind a reverse proxy, controls whether headers like X-Real-IP are accepted and allows X-Forwarded-\{Proto,Host,Uri\} headers to be used on redirect selection | false |
|
||||
| `--scope` | `scope` | string | OAuth scope specification | |
|
||||
| `--session-cookie-minimal` | `session_cookie_minimal` | bool | strip OAuth tokens from cookie session stores if they aren't needed (cookie session store only) | false |
|
||||
| `--session-store-type` | `session_store_type` | string | [Session data storage backend](sessions.md); redis or cookie | cookie |
|
||||
| `--set-xauthrequest` | `set_xauthrequest` | bool | set X-Auth-Request-User, X-Auth-Request-Groups, X-Auth-Request-Email and X-Auth-Request-Preferred-Username response headers (useful in Nginx auth_request mode). When used with `--pass-access-token`, X-Auth-Request-Access-Token is added to response headers. | false |
|
||||
| `--set-authorization-header` | `set_authorization_header` | bool | set Authorization Bearer response header (useful in Nginx auth_request mode) | false |
|
||||
| `--set-basic-auth` | `set_basic_auth` | bool | set HTTP Basic Auth information in response (useful in Nginx auth_request mode) | false |
|
||||
| `--show-debug-on-error` | `show_debug_on_error` | bool | show detailed error information on error pages (WARNING: this may contain sensitive information - do not use in production) | false |
|
||||
| `--signature-key` | `signature_key` | string | GAP-Signature request signature key (algorithm:secretkey) | |
|
||||
| `--silence-ping-logging` | `silence_ping_logging` | bool | disable logging of requests to ping & ready endpoints | false |
|
||||
| `--skip-auth-preflight` | `skip_auth_preflight` | bool | will skip authentication for OPTIONS requests | false |
|
||||
| `--skip-auth-regex` | `skip_auth_regex` | string \| list | (DEPRECATED for `--skip-auth-route`) bypass authentication for requests paths that match (may be given multiple times) | |
|
||||
| `--skip-auth-route` | `skip_auth_routes` | string \| list | bypass authentication for requests that match the method & path. Format: method=path_regex OR method!=path_regex. For all methods: path_regex OR !=path_regex | |
|
||||
| `--skip-auth-strip-headers` | `skip_auth_strip_headers` | bool | strips `X-Forwarded-*` style authentication headers & `Authorization` header if they would be set by oauth2-proxy | true |
|
||||
| `--skip-jwt-bearer-tokens` | `skip_jwt_bearer_tokens` | bool | will skip requests that have verified JWT bearer tokens (the token must have [`aud`](https://en.wikipedia.org/wiki/JSON_Web_Token#Standard_fields) that matches this client id or one of the extras from `extra-jwt-issuers`) | false |
|
||||
| `--skip-oidc-discovery` | `skip_oidc_discovery` | bool | bypass OIDC endpoint discovery. `--login-url`, `--redeem-url` and `--oidc-jwks-url` must be configured in this case | false |
|
||||
| `--skip-provider-button` | `skip_provider_button` | bool | will skip sign-in-page to directly reach the next step: oauth/start | false |
|
||||
| `--ssl-insecure-skip-verify` | `ssl_insecure_skip_verify` | bool | skip validation of certificates presented when using HTTPS providers | false |
|
||||
| `--ssl-upstream-insecure-skip-verify` | `ssl_upstream_insecure_skip_verify` | bool | skip validation of certificates presented when using HTTPS upstreams | false |
|
||||
| `--standard-logging` | `standard_logging` | bool | Log standard runtime information | true |
|
||||
| `--standard-logging-format` | `standard_logging_format` | string | Template for standard log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| `--tls-cert-file` | `tls_cert_file` | string | path to certificate file | |
|
||||
| `--tls-cipher-suite` | `tls_cipher_suites` | string \| list | Restricts TLS cipher suites used by server to those listed (e.g. TLS_RSA_WITH_RC4_128_SHA) (may be given multiple times). If not specified, the default Go safe cipher list is used. List of valid cipher suites can be found in the [crypto/tls documentation](https://pkg.go.dev/crypto/tls#pkg-constants). | |
|
||||
| `--tls-key-file` | `tls_key_file` | string | path to private key file | |
|
||||
| `--tls-min-version` | `tls_min_version` | string | minimum TLS version that is acceptable, either `"TLS1.2"` or `"TLS1.3"` | `"TLS1.2"` |
|
||||
| `--upstream` | `upstreams` | string \| list | the http url(s) of the upstream endpoint, file:// paths for static files or `static://<status_code>` for static response. Routing is based on the path | |
|
||||
| `--upstream-timeout` | `upstream_timeout` | duration | maximum amount of time the server will wait for a response from the upstream | 30s |
|
||||
| `--allowed-group` | `allowed_groups` | string \| list | restrict logins to members of this group (may be given multiple times) | |
|
||||
| `--allowed-role` | `allowed_roles` | string \| list | restrict logins to users with this role (may be given multiple times). Only works with the keycloak-oidc provider. | |
|
||||
| `--validate-url` | `validate_url` | string | Access token validation endpoint | |
|
||||
| `--version` | --- | n/a | print version string | |
|
||||
| `--whitelist-domain` | `whitelist_domains` | string \| list | allowed domains for redirection after authentication. Prefix domain with a `.` or a `*.` to allow subdomains (e.g. `.example.com`, `*.example.com`) [^2] | |
|
||||
| `--trusted-ip` | `trusted_ips` | string \| list | list of IPs or CIDR ranges to allow to bypass authentication (may be given multiple times). When combined with `--reverse-proxy` and optionally `__real_client_ip_header` this will evaluate the trust of the IP stored in an HTTP header by a reverse proxy rather than the layer-3/4 remote address. WARNING: trusting IPs has inherent security flaws, especially when obtaining the IP address from an HTTP header (reverse-proxy mode). Use this option only if you understand the risks and how to manage them. | |
|
||||
| `--encode-state` | `encode_state` | bool | encode the state parameter as UrlEncodedBase64 | false |
|
||||
| Flag | Description |
|
||||
| ----------- | -------------------- |
|
||||
| `--config` | path to config file |
|
||||
| `--version` | print version string |
|
||||
|
||||
### General Provider Options
|
||||
|
||||
Provider specific options can be found on their respective subpages.
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| --------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
||||
| flag: `--acr-values`<br/>toml: `acr_values` | string | optional, see [docs](https://openid.net/specs/openid-connect-eap-acr-values-1_0.html#acrValues) | `""` |
|
||||
| flag: `--allowed-group`<br/>toml: `allowed_groups` | string \| list | restrict logins to members of this group (may be given multiple times) | |
|
||||
| flag: `--approval-prompt`<br/>toml: `approval_prompt` | string | OAuth approval_prompt | `"force"` |
|
||||
| flag: `--backend-logout-url`<br/>toml: `backend_logout_url` | string | URL to perform backend logout, if you use `{id_token}` in the url it will be replaced by the actual `id_token` of the user session | |
|
||||
| flag: `--client-id`<br/>toml: `client_id` | string | the OAuth Client ID, e.g. `"123456.apps.googleusercontent.com"` | |
|
||||
| flag: `--client-secret-file`<br/>toml: `client_secret_file` | string | the file with OAuth Client Secret | |
|
||||
| flag: `--client-secret`<br/>toml: `client_secret` | string | the OAuth Client Secret | |
|
||||
| flag: `--code-challenge-method`<br/>toml: `code_challenge_method` | string | use PKCE code challenges with the specified method. Either 'plain' or 'S256' (recommended) | |
|
||||
| flag: `--insecure-oidc-allow-unverified-email`<br/>toml: `insecure_oidc_allow_unverified_email` | bool | don't fail if an email address in an id_token is not verified | false |
|
||||
| flag: `--insecure-oidc-skip-issuer-verification`<br/>toml: `insecure_oidc_skip_issuer_verification` | bool | allow the OIDC issuer URL to differ from the expected (currently required for Azure multi-tenant compatibility) | false |
|
||||
| flag: `--insecure-oidc-skip-nonce`<br/>toml: `insecure_oidc_skip_nonce` | bool | skip verifying the OIDC ID Token's nonce claim | true |
|
||||
| flag: `--jwt-key-file`<br/>toml: `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 | |
|
||||
| flag: `--jwt-key`<br/>toml: `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 | |
|
||||
| flag: `--login-url`<br/>toml: `login_url` | string | Authentication endpoint | |
|
||||
| flag: `--oidc-audience-claim`<br/>toml: `oidc_audience_claims` | string | which OIDC claim contains the audience | `"aud"` |
|
||||
| flag: `--oidc-email-claim`<br/>toml: `oidc_email_claim` | string | which OIDC claim contains the user's email | `"email"` |
|
||||
| flag: `--oidc-extra-audience`<br/>toml: `oidc_extra_audiences` | string \| list | additional audiences which are allowed to pass verification | `"[]"` |
|
||||
| flag: `--oidc-groups-claim`<br/>toml: `oidc_groups_claim` | string | which OIDC claim contains the user groups | `"groups"` |
|
||||
| flag: `--oidc-issuer-url`<br/>toml: `oidc_issuer_url` | string | the OpenID Connect issuer URL, e.g. `"https://accounts.google.com"` | |
|
||||
| flag: `--oidc-jwks-url`<br/>toml: `oidc_jwks_url` | string | OIDC JWKS URI for token verification; required if OIDC discovery is disabled | |
|
||||
| flag: `--profile-url`<br/>toml: `profile_url` | string | Profile access endpoint | |
|
||||
| flag: `--prompt`<br/>toml: `prompt` | string | [OIDC prompt](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest); if present, `approval-prompt` is ignored | `""` |
|
||||
| flag: `--provider-ca-file`<br/>toml: `provider_ca_file` | string \| list | Paths to CA certificates that should be used when connecting to the provider. If not specified, the default Go trust sources are used instead. |
|
||||
| flag: `--provider-display-name`<br/>toml: `provider_display_name` | string | Override the provider's name with the given string; used for the sign-in page | (depends on provider) |
|
||||
| flag: `--provider`<br/>toml: `provider` | string | OAuth provider | google |
|
||||
| flag: `--pubjwk-url`<br/>toml: `pubjwk_url` | string | JWK pubkey access endpoint: required by login.gov | |
|
||||
| flag: `--redeem-url`<br/>toml: `redeem_url` | string | Token redemption endpoint | |
|
||||
| flag: `--scope`<br/>toml:`scope` | string | OAuth scope specification | |
|
||||
| flag: `--skip-claims-from-profile-url`<br/>toml: `skip_claims_from_profile_url` | bool | skip request to Profile URL for resolving claims not present in id_token | false |
|
||||
| flag: `--skip-oidc-discovery`<br/>toml: `skip_oidc_discovery` | bool | bypass OIDC endpoint discovery. `--login-url`, `--redeem-url` and `--oidc-jwks-url` must be configured in this case | false |
|
||||
| flag: `--use-system-trust-store`<br/>toml: `use_system_trust_store` | bool | Determines if `provider-ca-file` files and the system trust store are used. If set to true, your custom CA files and the system trust store are used otherwise only your custom CA files. | false |
|
||||
| flag: `--validate-url`<br/>toml: `validate_url` | string | Access token validation endpoint | |
|
||||
|
||||
### Cookie Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| -------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
||||
| flag: `--cookie-csrf-expire`<br/>toml: `cookie_csrf_expire` | duration | expire timeframe for CSRF cookie | 15m |
|
||||
| flag: `--cookie-csrf-per-request`<br/>toml:`cookie_csrf_per_request` | bool | Enable having different CSRF cookies per request, making it possible to have parallel requests. | false |
|
||||
| flag: `--cookie-domain`<br/>toml: `cookie_domains` | string \| list | Optional cookie domains to force cookies to (e.g. `.yourcompany.com`). The longest domain matching the request's host will be used (or the shortest cookie domain if there is no match). | |
|
||||
| flag: `--cookie-expire`<br/>toml: `cookie_expire` | duration | expire timeframe for cookie. If set to 0, cookie becomes a session-cookie which will expire when the browser is closed. | 168h0m0s |
|
||||
| flag: `--cookie-httponly`<br/>toml: `cookie_httponly` | bool | set HttpOnly cookie flag | true |
|
||||
| flag: `--cookie-name`<br/>toml: `cookie_name` | string | the name of the cookie that the oauth_proxy creates. Should be changed to use a [cookie prefix](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes) (`__Host-` or `__Secure-`) if `--cookie-secure` is set. | `"_oauth2_proxy"` |
|
||||
| flag: `--cookie-path`<br/>toml: `cookie_path` | string | an optional cookie path to force cookies to (e.g. `/poc/`) | `"/"` |
|
||||
| flag: `--cookie-refresh`<br/>toml: `cookie_refresh` | duration | refresh the cookie after this duration; `0` to disable; not supported by all providers [^1] | |
|
||||
| flag: `--cookie-samesite`<br/>toml: `cookie_samesite` | string | set SameSite cookie attribute (`"lax"`, `"strict"`, `"none"`, or `""`). | `""` |
|
||||
| flag: `--cookie-secret`<br/>toml: `cookie_secret` | string | the seed string for secure cookies (optionally base64 encoded) | |
|
||||
| flag: `--cookie-secure`<br/>toml: `cookie_secure` | bool | set [secure (HTTPS only) cookie flag](https://owasp.org/www-community/controls/SecureFlag) | true |
|
||||
|
||||
[^1]: The following providers support `--cookie-refresh`: ADFS, Azure, GitLab, Google, Keycloak and all other Identity Providers which support the full [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens)
|
||||
|
||||
### Header Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| flag: `--basic-auth-password`<br/>toml: `basic_auth_password` | string | the password to set when passing the HTTP Basic Auth header | |
|
||||
| flag: `--set-xauthrequest`<br/>toml: `set_xauthrequest` | bool | set X-Auth-Request-User, X-Auth-Request-Groups, X-Auth-Request-Email and X-Auth-Request-Preferred-Username response headers (useful in Nginx auth_request mode). When used with `--pass-access-token`, X-Auth-Request-Access-Token is added to response headers. | false |
|
||||
| flag: `--set-authorization-header`<br/>toml: `set_authorization_header` | bool | set Authorization Bearer response header (useful in Nginx auth_request mode) | false |
|
||||
| flag: `--set-basic-auth`<br/>toml: `set_basic_auth` | bool | set HTTP Basic Auth information in response (useful in Nginx auth_request mode) | false |
|
||||
| flag: `--skip-auth-strip-headers`<br/>toml: `skip_auth_strip_headers` | bool | strips `X-Forwarded-*` style authentication headers & `Authorization` header if they would be set by oauth2-proxy | true |
|
||||
| flag: `--pass-access-token`<br/>toml: `pass_access_token` | bool | pass OAuth access_token to upstream via X-Forwarded-Access-Token header. When used with `--set-xauthrequest` this adds the X-Auth-Request-Access-Token header to the response | false |
|
||||
| flag: `--pass-authorization-header`<br/>toml: `pass_authorization_header` | bool | pass OIDC IDToken to upstream via Authorization Bearer header | false |
|
||||
| flag: `--pass-basic-auth`<br/>toml: `pass_basic_auth` | bool | pass HTTP Basic Auth, X-Forwarded-User, X-Forwarded-Email and X-Forwarded-Preferred-Username information to upstream | true |
|
||||
| flag: `--prefer-email-to-user`<br/>toml: `prefer_email_to_user` | bool | Prefer to use the Email address as the Username when passing information to upstream. Will only use Username if Email is unavailable, e.g. htaccess authentication. Used in conjunction with `--pass-basic-auth` and `--pass-user-headers` | false |
|
||||
| flag: `--pass-user-headers`<br/>toml: `pass_user_headers` | bool | pass X-Forwarded-User, X-Forwarded-Groups, X-Forwarded-Email and X-Forwarded-Preferred-Username information to upstream | true |
|
||||
|
||||
### Logging Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| --------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| flag: `--auth-logging-format`<br/>toml: `auth_logging_format` | string | Template for authentication log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| flag: `--auth-logging`<br/>toml: `auth_logging` | bool | Log authentication attempts | true |
|
||||
| flag: `--errors-to-info-log`<br/>toml: `errors_to_info_log` | bool | redirects error-level logging to default log channel instead of stderr | false |
|
||||
| flag: `--exclude-logging-path`<br/>toml: `exclude_logging_paths` | string | comma separated list of paths to exclude from logging, e.g. `"/ping,/path2"` | `""` (no paths excluded) |
|
||||
| flag: `--logging-compress`<br/>toml: `logging_compress` | bool | Should rotated log files be compressed using gzip | false |
|
||||
| flag: `--logging-filename`<br/>toml: `logging_filename` | string | File to log requests to, empty for `stdout` | `""` (stdout) |
|
||||
| flag: `--logging-local-time`<br/>toml: `logging_local_time` | bool | Use local time in log files and backup filenames instead of UTC | true (local time) |
|
||||
| flag: `--logging-max-age`<br/>toml: `logging_max_age` | int | Maximum number of days to retain old log files | 7 |
|
||||
| flag: `--logging-max-backups`<br/>toml: `logging_max_backups` | int | Maximum number of old log files to retain; 0 to disable | 0 |
|
||||
| flag: `--logging-max-size`<br/>toml: `logging_max_size` | int | Maximum size in megabytes of the log file before rotation | 100 |
|
||||
| flag: `--request-id-header`<br/>toml: `request_id_header` | string | Request header to use as the request ID in logging | X-Request-Id |
|
||||
| flag: `--request-logging-format`<br/>toml: `request_logging_format` | string | Template for request log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| flag: `--request-logging`<br/>toml: `request_logging` | bool | Log requests | true |
|
||||
| flag: `--silence-ping-logging`<br/>toml: `silence_ping_logging` | bool | disable logging of requests to ping & ready endpoints | false |
|
||||
| flag: `--standard-logging-format`<br/>toml: `standard_logging_format` | string | Template for standard log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| flag: `--standard-logging`<br/>toml: `standard_logging` | bool | Log standard runtime information | true |
|
||||
|
||||
### Page Template Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ----------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| flag: `--banner`<br/>toml: `banner` | string | custom (html) banner string. Use `"-"` to disable default banner. | |
|
||||
| flag: `--custom-sign-in-logo`<br/>toml: `custom_sign_in_logo` | string | path or a URL to an custom image for the sign_in page logo. Use `"-"` to disable default logo. |
|
||||
| flag: `--custom-templates-dir`<br/>toml: `custom_templates_dir` | string | path to custom html templates | |
|
||||
| flag: `--display-htpasswd-form`<br/>toml: `display_htpasswd_form` | bool | display username / password login form if an htpasswd file is provided | true |
|
||||
| flag: `--footer`<br/>toml: `footer` | string | custom (html) footer string. Use `"-"` to disable default footer. | |
|
||||
| flag: `--show-debug-on-error`<br/>toml: `show_debug_on_error` | bool | show detailed error information on error pages (WARNING: this may contain sensitive information - do not use in production) | false |
|
||||
|
||||
### Probe Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ------------------------------------------------------- | ------ | ---------------------------------------------------------- | ----------------------------- |
|
||||
| flag: `--ping-path`<br/>toml: `ping_path` | string | the ping endpoint that can be used for basic health checks | `"/ping"` |
|
||||
| flag: `--ping-user-agent`<br/>toml: `ping_user_agent` | string | a User-Agent that can be used for basic health checks | `""` (don't check user agent) |
|
||||
| flag: `--ready-path`<br/>toml: `ready_path` | string | the ready endpoint that can be used for deep health checks | `"/ready"` |
|
||||
| flag: `--gcp-healthchecks`<br/>toml: `gcp_healthchecks` | bool | Enable GCP/GKE healthcheck endpoints (deprecated) | false |
|
||||
|
||||
### Proxy Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
|
||||
| flag: `--allow-query-semicolons`<br/>toml: `allow_query_semicolons` | bool | allow the use of semicolons in query args ([required for some legacy applications](https://github.com/golang/go/issues/25192)) | `false` |
|
||||
| flag: `--api-route`<br/>toml: `api_routes` | string \| list | return HTTP 401 instead of redirecting to authentication server if token is not valid. Format: path_regex | |
|
||||
| flag: `--authenticated-emails-file`<br/>toml: `authenticated_emails_file` | string | authenticate against emails via file (one per line) | |
|
||||
| flag: `--email-domain`<br/>toml: `email_domains` | string \| list | authenticate emails with the specified domain (may be given multiple times). Use `*` to authenticate any email | |
|
||||
| flag: `--encode-state`<br/>toml: `encode_state` | bool | encode the state parameter as UrlEncodedBase64 | false |
|
||||
| flag: `--extra-jwt-issuers`<br/>toml: `extra_jwt_issuers` | string | if `--skip-jwt-bearer-tokens` is set, a list of extra JWT `issuer=audience` (see a token's `iss`, `aud` fields) pairs (where the issuer URL has a `.well-known/openid-configuration` or a `.well-known/jwks.json`) | |
|
||||
| flag: `--force-https`<br/>toml: `force_https` | bool | enforce https redirect | `false` |
|
||||
| flag: `--force-json-errors`<br/>toml: `force_json_errors` | bool | force JSON errors instead of HTTP error pages or redirects | `false` |
|
||||
| flag: `--htpasswd-file`<br/>toml: `htpasswd_file` | string | additionally authenticate against a htpasswd file. Entries must be created with `htpasswd -B` for bcrypt encryption | |
|
||||
| flag: `--htpasswd-user-group`<br/>toml: `htpasswd_user_groups` | string \| list | the groups to be set on sessions for htpasswd users | |
|
||||
| flag: `--proxy-prefix`<br/>toml: `proxy_prefix` | string | the url root path that this proxy should be nested under (e.g. /`<oauth2>/sign_in`) | `"/oauth2"` |
|
||||
| flag: `--real-client-ip-header`<br/>toml: `real_client_ip_header` | string | Header used to determine the real IP of the client, requires `--reverse-proxy` to be set (one of: X-Forwarded-For, X-Real-IP, or X-ProxyUser-IP) | X-Real-IP |
|
||||
| flag: `--redirect-url`<br/>toml: `redirect_url` | string | the OAuth Redirect URL, e.g. `"https://internalapp.yourcompany.com/oauth2/callback"` | |
|
||||
| flag: `--relative-redirect-url`<br/>toml: `relative_redirect_url` | bool | allow relative OAuth Redirect URL.` | false |
|
||||
| flag: `--reverse-proxy`<br/>toml: `reverse_proxy` | bool | are we running behind a reverse proxy, controls whether headers like X-Real-IP are accepted and allows X-Forwarded-\{Proto,Host,Uri\} headers to be used on redirect selection | false |
|
||||
| flag: `--signature-key`<br/>toml: `signature_key` | string | GAP-Signature request signature key (algorithm:secretkey) | |
|
||||
| flag: `--skip-auth-preflight`<br/>toml: `skip_auth_preflight` | bool | will skip authentication for OPTIONS requests | false |
|
||||
| flag: `--skip-auth-regex`<br/>toml: `skip_auth_regex` | string \| list | (DEPRECATED for `--skip-auth-route`) bypass authentication for requests paths that match (may be given multiple times) | |
|
||||
| flag: `--skip-auth-route`<br/>toml: `skip_auth_routes` | string \| list | bypass authentication for requests that match the method & path. Format: method=path_regex OR method!=path_regex. For all methods: path_regex OR !=path_regex | |
|
||||
| flag: `--skip-jwt-bearer-tokens`<br/>toml: `skip_jwt_bearer_tokens` | bool | will skip requests that have verified JWT bearer tokens (the token must have [`aud`](https://en.wikipedia.org/wiki/JSON_Web_Token#Standard_fields) that matches this client id or one of the extras from `extra-jwt-issuers`) | false |
|
||||
| flag: `--skip-provider-button`<br/>toml: `skip_provider_button` | bool | will skip sign-in-page to directly reach the next step: oauth/start | false |
|
||||
| flag: `--ssl-insecure-skip-verify`<br/>toml: `ssl_insecure_skip_verify` | bool | skip validation of certificates presented when using HTTPS providers | false |
|
||||
| flag: `--trusted-ip`<br/>toml: `trusted_ips` | bool | encode the state parameter as UrlEncodedBase64 | false |
|
||||
| flag: `--whitelist-domain`<br/>toml: `whitelist_domains` | string \| list | allowed domains for redirection after authentication. Prefix domain with a `.` or a `*.` to allow subdomains (e.g. `.example.com`, `*.example.com`) [^2] | |
|
||||
|
||||
[^2]: When using the `whitelist-domain` option, any domain prefixed with a `.` or a `*.` will allow any subdomain of the specified domain as a valid redirect URL. By default, only empty ports are allowed. This translates to allowing the default port of the URL's protocol (80 for HTTP, 443 for HTTPS, etc.) since browsers omit them. To allow only a specific port, add it to the whitelisted domain: `example.com:8080`. To allow any port, use `*`: `example.com:*`.
|
||||
|
||||
See below for provider specific options
|
||||
### Server Options
|
||||
|
||||
### Upstreams Configuration
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
|
||||
| flag: `--http-address`<br/>toml: `http_address` | string | `[http://]<addr>:<port>` or `unix://<path>` to listen on for HTTP clients. Square brackets are required for ipv6 address, e.g. `http://[::1]:4180` | `"127.0.0.1:4180"` |
|
||||
| flag: `--https-address`<br/>toml: `https_address` | string | `[https://]<addr>:<port>` to listen on for HTTPS clients. Square brackets are required for ipv6 address, e.g. `https://[::1]:443` | `":443"` |
|
||||
| flag: `--metrics-address`<br/>toml: `metrics_address` | string | the address prometheus metrics will be scraped from | `""` |
|
||||
| flag: `--metrics-secure-address`<br/>toml: `metrics_secure_address` | string | the address prometheus metrics will be scraped from if using HTTPS | `""` |
|
||||
| flag: `--metrics-tls-cert-file`<br/>toml: `metrics_tls_cert_file` | string | path to certificate file for secure metrics server | `""` |
|
||||
| flag: `--metrics-tls-key-file`<br/>toml: `metrics_tls_key_file` | string | path to private key file for secure metrics server | `""` |
|
||||
| flag: `--tls-cert-file`<br/>toml: `tls_cert_file` | string | path to certificate file | |
|
||||
| flag: `--tls-key-file`<br/>toml: `tls_key_file` | string | path to private key file | |
|
||||
| flag: `--tls-cipher-suite`<br/>toml: `tls_cipher_suites` | string \| list | Restricts TLS cipher suites used by server to those listed (e.g. TLS_RSA_WITH_RC4_128_SHA) (may be given multiple times). If not specified, the default Go safe cipher list is used. List of valid cipher suites can be found in the [crypto/tls documentation](https://pkg.go.dev/crypto/tls#pkg-constants). | |
|
||||
| flag: `--tls-min-version`<br/>toml: `tls_min_version` | string | minimum TLS version that is acceptable, either `"TLS1.2"` or `"TLS1.3"` | `"TLS1.2"` |
|
||||
|
||||
### Session Options
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ----------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| flag: `--session-cookie-minimal`<br/>toml: `session_cookie_minimal` | bool | strip OAuth tokens from cookie session stores if they aren't needed (cookie session store only) | false |
|
||||
| flag: `--session-store-type`<br/>toml: `session_store_type` | string | [Session data storage backend](sessions.md); redis or cookie | cookie |
|
||||
| flag: `--redis-cluster-connection-urls`<br/>toml: `redis_cluster_connection_urls` | string \| list | List of Redis cluster connection URLs (e.g. `redis://HOST[:PORT]`). Used in conjunction with `--redis-use-cluster` | |
|
||||
| flag: `--redis-connection-url`<br/>toml: `redis_connection_url` | string | URL of redis server for redis session storage (e.g. `redis://HOST[:PORT]`) | |
|
||||
| flag: `--redis-insecure-skip-tls-verify`<br/>toml: `redis_insecure_skip_tls_verify` | bool | skip TLS verification when connecting to Redis | false |
|
||||
| flag: `--redis-password`<br/>toml: `redis_password` | string | Redis password. Applicable for all Redis configurations. Will override any password set in `--redis-connection-url` | |
|
||||
| flag: `--redis-sentinel-password`<br/>toml: `redis_sentinel_password` | string | Redis sentinel password. Used only for sentinel connection; any redis node passwords need to use `--redis-password` | |
|
||||
| flag: `--redis-sentinel-master-name`<br/>toml: `redis_sentinel_master_name` | string | Redis sentinel master name. Used in conjunction with `--redis-use-sentinel` | |
|
||||
| flag: `--redis-sentinel-connection-urls`<br/>toml: `redis_sentinel_connection_urls` | string \| list | List of Redis sentinel connection URLs (e.g. `redis://HOST[:PORT]`). Used in conjunction with `--redis-use-sentinel` | |
|
||||
| flag: `--redis-use-cluster`<br/>toml: `redis_use_cluster` | bool | Connect to redis cluster. Must set `--redis-cluster-connection-urls` to use this feature | false |
|
||||
| flag: `--redis-use-sentinel`<br/>toml: `redis_use_sentinel` | bool | Connect to redis via sentinels. Must set `--redis-sentinel-master-name` and `--redis-sentinel-connection-urls` to use this feature | false |
|
||||
| flag: `--redis-connection-idle-timeout`<br/>toml: `redis_connection_idle_timeout` | int | Redis connection idle timeout seconds. If Redis [timeout](https://redis.io/docs/reference/clients/#client-timeouts) option is set to non-zero, the `--redis-connection-idle-timeout` must be less than Redis timeout option. Example: if either redis.conf includes `timeout 15` or using `CONFIG SET timeout 15` the `--redis-connection-idle-timeout` must be at least `--redis-connection-idle-timeout=14` | 0 |
|
||||
|
||||
### Upstream Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ----------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
|
||||
| flag: `--flush-interval`<br/>toml: `flush_interval` | duration | period between flushing response buffers when streaming responses | `"1s"` |
|
||||
| flag: `--pass-host-header`<br/>toml: `pass_host_header` | bool | pass the request Host Header to upstream | true |
|
||||
| flag: `--proxy-websockets`<br/>toml: `proxy_websockets` | bool | enables WebSocket proxying | true |
|
||||
| flag: `--ssl-upstream-insecure-skip-verify`<br/>toml: `ssl_upstream_insecure_skip_verify` | bool | skip validation of certificates presented when using HTTPS upstreams | false |
|
||||
| flag: `--upstream-timeout`<br/>toml: `upstream_timeout` | duration | maximum amount of time the server will wait for a response from the upstream | 30s |
|
||||
| flag: `--upstream`<br/>toml: `upstreams` | string \| list | the http url(s) of the upstream endpoint, file:// paths for static files or `static://<status_code>` for static response. Routing is based on the path | |
|
||||
|
||||
## 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.
|
||||
|
||||
@ -228,7 +269,7 @@ Static file paths are configured as a file:// URL. `file:///var/www/static/` wil
|
||||
|
||||
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](#config-file). When multiple upstreams are used routing to them will be based on the path they are set up with.
|
||||
|
||||
### Environment variables
|
||||
## Environment variables
|
||||
|
||||
Every command line argument can be specified as an environment variable by
|
||||
prefixing it with `OAUTH2_PROXY_`, capitalising it, and replacing hyphens (`-`)
|
||||
@ -253,7 +294,7 @@ Each type of logging has its own configurable format and variables. By default,
|
||||
|
||||
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
|
||||
## 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:
|
||||
|
||||
```
|
||||
@ -288,7 +329,7 @@ Available variables for auth logging:
|
||||
| Username | username@email.com | The email or username of the auth request. |
|
||||
| Status | AuthSuccess | The status of the auth request. See above for details. |
|
||||
|
||||
### Request Log Format
|
||||
## Request Log Format
|
||||
HTTP request logs will output by default in the below format:
|
||||
|
||||
```
|
||||
@ -320,7 +361,7 @@ Available variables for request logging:
|
||||
| UserAgent | - | The full user agent as reported by the requesting client. |
|
||||
| Username | username@email.com | The email or username of the auth request. |
|
||||
|
||||
### Standard Log Format
|
||||
## 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:
|
||||
|
||||
```
|
||||
@ -340,269 +381,3 @@ Available variables for standard logging:
|
||||
| Timestamp | 2015/03/19 17:20:19 | The date and time of the logging event. |
|
||||
| File | main.go:40 | The file and line number of the logging statement. |
|
||||
| Message | HTTP: listening on 127.0.0.1:4180 | The details of the log statement. |
|
||||
|
||||
## Configuring for use with the Nginx `auth_request` directive
|
||||
|
||||
**This option requires `--reverse-proxy` option to be set.**
|
||||
|
||||
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:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name ...;
|
||||
include ssl/ssl.conf;
|
||||
|
||||
location /oauth2/ {
|
||||
proxy_pass http://127.0.0.1:4180;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Auth-Request-Redirect $request_uri;
|
||||
# or, if you are handling multiple domains:
|
||||
# proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri;
|
||||
}
|
||||
location = /oauth2/auth {
|
||||
proxy_pass http://127.0.0.1:4180;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-Uri $request_uri;
|
||||
# nginx auth_request includes headers but not body
|
||||
proxy_set_header Content-Length "";
|
||||
proxy_pass_request_body off;
|
||||
}
|
||||
|
||||
location / {
|
||||
auth_request /oauth2/auth;
|
||||
error_page 401 =403 /oauth2/sign_in;
|
||||
|
||||
# pass information via X-User and X-Email headers to backend,
|
||||
# requires running with --set-xauthrequest flag
|
||||
auth_request_set $user $upstream_http_x_auth_request_user;
|
||||
auth_request_set $email $upstream_http_x_auth_request_email;
|
||||
proxy_set_header X-User $user;
|
||||
proxy_set_header X-Email $email;
|
||||
|
||||
# if you enabled --pass-access-token, this will pass the token to the backend
|
||||
auth_request_set $token $upstream_http_x_auth_request_access_token;
|
||||
proxy_set_header X-Access-Token $token;
|
||||
|
||||
# if you enabled --cookie-refresh, this is needed for it to work with auth_request
|
||||
auth_request_set $auth_cookie $upstream_http_set_cookie;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
|
||||
# When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb
|
||||
# limit and so the OAuth2 Proxy splits these into multiple parts.
|
||||
# Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,
|
||||
# so if your cookies are larger than 4kb, you will need to extract additional cookies manually.
|
||||
auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
|
||||
|
||||
# Extract the Cookie attributes from the first Set-Cookie header and append them
|
||||
# to the second part ($upstream_cookie_* variables only contain the raw cookie content)
|
||||
if ($auth_cookie ~* "(; .*)") {
|
||||
set $auth_cookie_name_0 $auth_cookie;
|
||||
set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
|
||||
}
|
||||
|
||||
# Send both Set-Cookie headers now if there was a second part
|
||||
if ($auth_cookie_name_upstream_1) {
|
||||
add_header Set-Cookie $auth_cookie_name_0;
|
||||
add_header Set-Cookie $auth_cookie_name_1;
|
||||
}
|
||||
|
||||
proxy_pass http://backend/;
|
||||
# or "root /path/to/site;" or "fastcgi_pass ..." etc
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When you use ingress-nginx in Kubernetes, you MUST use `kubernetes/ingress-nginx` (which includes the Lua module) and the following configuration snippet for your `Ingress`.
|
||||
Variables set with `auth_request_set` are not `set`-able in plain nginx config when the location is processed via `proxy_pass` and then may only be processed by Lua.
|
||||
Note that `nginxinc/kubernetes-ingress` does not include the Lua module.
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/auth-response-headers: Authorization
|
||||
nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$escaped_request_uri
|
||||
nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
|
||||
nginx.ingress.kubernetes.io/configuration-snippet: |
|
||||
auth_request_set $name_upstream_1 $upstream_cookie_name_1;
|
||||
|
||||
access_by_lua_block {
|
||||
if ngx.var.name_upstream_1 ~= "" then
|
||||
ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
|
||||
end
|
||||
}
|
||||
```
|
||||
It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
|
||||
|
||||
You have to substitute *name* 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=".
|
||||
|
||||
## Configuring for use with the Traefik (v2) `ForwardAuth` middleware
|
||||
|
||||
**This option requires `--reverse-proxy` option to be set.**
|
||||
|
||||
### ForwardAuth with 401 errors middleware
|
||||
|
||||
The [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) allows Traefik to authenticate requests via the oauth2-proxy's `/oauth2/auth` endpoint on every request, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the whole request through. For example, on Dynamic File (YAML) Configuration:
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
a-service:
|
||||
rule: "Host(`a-service.example.com`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-errors
|
||||
- oauth-auth
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
oauth:
|
||||
rule: "Host(`a-service.example.com`, `oauth.example.com`) && PathPrefix(`/oauth2/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
|
||||
services:
|
||||
a-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.2:7555
|
||||
oauth-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.1:4180
|
||||
|
||||
middlewares:
|
||||
auth-headers:
|
||||
headers:
|
||||
sslRedirect: true
|
||||
stsSeconds: 315360000
|
||||
browserXssFilter: true
|
||||
contentTypeNosniff: true
|
||||
forceSTSHeader: true
|
||||
sslHost: example.com
|
||||
stsIncludeSubdomains: true
|
||||
stsPreload: true
|
||||
frameDeny: true
|
||||
oauth-auth:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/oauth2/auth
|
||||
trustForwardHeader: true
|
||||
oauth-errors:
|
||||
errors:
|
||||
status:
|
||||
- "401-403"
|
||||
service: oauth-backend
|
||||
query: "/oauth2/sign_in?rd={url}"
|
||||
```
|
||||
|
||||
### ForwardAuth with static upstreams configuration
|
||||
|
||||
Redirect to sign_in functionality provided without the use of `errors` middleware with [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) pointing to oauth2-proxy service's `/` endpoint
|
||||
|
||||
**Following options need to be set on `oauth2-proxy`:**
|
||||
- `--upstream=static://202`: Configures a static response for authenticated sessions
|
||||
- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
a-service-route-1:
|
||||
rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-auth-redirect # redirects all unauthenticated to oauth2 signin
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
a-service-route-2:
|
||||
rule: "Host(`a-service.example.com`) && PathPrefix(`/no-auto-redirect`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-auth-wo-redirect # unauthenticated session will return a 401
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
services-oauth2-route:
|
||||
rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/oauth2/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
oauth2-proxy-route:
|
||||
rule: "Host(`oauth.example.com`) && PathPrefix(`/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
|
||||
services:
|
||||
a-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.2:7555
|
||||
b-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.3:7555
|
||||
oauth-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.1:4180
|
||||
|
||||
middlewares:
|
||||
auth-headers:
|
||||
headers:
|
||||
sslRedirect: true
|
||||
stsSeconds: 315360000
|
||||
browserXssFilter: true
|
||||
contentTypeNosniff: true
|
||||
forceSTSHeader: true
|
||||
sslHost: example.com
|
||||
stsIncludeSubdomains: true
|
||||
stsPreload: true
|
||||
frameDeny: true
|
||||
oauth-auth-redirect:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/
|
||||
trustForwardHeader: true
|
||||
authResponseHeaders:
|
||||
- X-Auth-Request-Access-Token
|
||||
- Authorization
|
||||
oauth-auth-wo-redirect:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/oauth2/auth
|
||||
trustForwardHeader: true
|
||||
authResponseHeaders:
|
||||
- X-Auth-Request-Access-Token
|
||||
- Authorization
|
||||
```
|
||||
|
||||
:::note
|
||||
If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
|
||||
:::
|
||||
|
||||
@ -3,6 +3,15 @@ id: azure
|
||||
title: Azure
|
||||
---
|
||||
|
||||
## Config Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ---------------- | -------------- | ------ | ---------------------------------------------------------------- | ---------- |
|
||||
| `--azure-tenant` | `azure_tenant` | string | go to a tenant-specific or common (tenant-independent) endpoint. | `"common"` |
|
||||
| `--resource` | `resource` | string | The resource that is protected (Azure AD only) | |
|
||||
|
||||
## Usage
|
||||
|
||||
1. Add an application: go to [https://portal.azure.com](https://portal.azure.com), choose **Azure Active Directory**, select
|
||||
**App registrations** and then click on **New registration**.
|
||||
2. Pick a name, check the supported account type(single-tenant, multi-tenant, etc). In the **Redirect URI** section create a new
|
||||
|
||||
@ -3,6 +3,15 @@ id: azure_ad
|
||||
title: Microsoft Azure AD
|
||||
---
|
||||
|
||||
## Config Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ---------------- | -------------- | ------ | ---------------------------------------------------------------- | ---------- |
|
||||
| `--azure-tenant` | `azure_tenant` | string | go to a tenant-specific or common (tenant-independent) endpoint. | `"common"` |
|
||||
| `--resource` | `resource` | string | The resource that is protected (Azure AD only) | |
|
||||
|
||||
## Usage
|
||||
|
||||
For adding an application to the Microsoft Azure AD follow [these steps to add an application](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app).
|
||||
|
||||
Take note of your `TenantId` if applicable for your situation. The `TenantId` can be used to override the default
|
||||
|
||||
@ -3,6 +3,18 @@ id: github
|
||||
title: GitHub
|
||||
---
|
||||
|
||||
## Config Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ---------------- | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| `--github-org` | `github_org` | string | restrict logins to members of this organisation | |
|
||||
| `--github-team` | `github_team` | string | restrict logins to members of any of these teams (slug), separated by a comma | |
|
||||
| `--github-repo` | `github_repo` | string | restrict logins to collaborators of this repository formatted as `orgname/repo` | |
|
||||
| `--github-token` | `github_token` | string | the token to use when verifying repository collaborators (must have push access to the repository) | |
|
||||
| `--github-user` | `github_users` | string \| list | To allow users to login by username even if they do not belong to the specified org and team or collaborators | |
|
||||
|
||||
## Usage
|
||||
|
||||
1. Create a new project: https://github.com/settings/developers
|
||||
2. Under `Authorization callback URL` enter the correct url ie `https://internal.yourcompany.com/oauth2/callback`
|
||||
|
||||
|
||||
@ -3,6 +3,15 @@ id: gitlab
|
||||
title: GitLab
|
||||
---
|
||||
|
||||
## Config Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ------------------- | ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| `--gitlab-group` | `gitlab_groups` | string \| list | restrict logins to members of any of these groups (slug), separated by a comma | |
|
||||
| `--gitlab-projects` | `gitlab_projects` | string \| list | restrict logins to members of any of these projects (may be given multiple times) formatted as `orgname/repo=accesslevel`. Access level should be a value matching [Gitlab access levels](https://docs.gitlab.com/ee/api/members.html#valid-access-levels), defaulted to 20 if absent | |
|
||||
|
||||
## Usage
|
||||
|
||||
This auth provider has been tested against Gitlab version 12.X. Due to Gitlab API changes, it may not work for version
|
||||
prior to 12.X (see [994](https://github.com/oauth2-proxy/oauth2-proxy/issues/994)).
|
||||
|
||||
|
||||
@ -3,6 +3,18 @@ id: google
|
||||
title: Google (default)
|
||||
---
|
||||
|
||||
## Config Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ---------------------------------------------- | -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
|
||||
| `--google-admin-email` | `google_admin_email` | string | the google admin to impersonate for api calls | |
|
||||
| `--google-group` | `google_groups` | string | restrict logins to members of this google group (may be given multiple times). | |
|
||||
| `--google-service-account-json` | `google_service_account_json` | string | the path to the service account json credentials | |
|
||||
| `--google-use-application-default-credentials` | `google_use_application_default_credentials` | bool | use application default credentials instead of service account json (i.e. GKE Workload Identity) | |
|
||||
| `--google-target-principal` | `google_target_principal` | bool | the target principal to impersonate when using ADC | defaults to the service account configured for ADC |
|
||||
|
||||
## Usage
|
||||
|
||||
For Google, the registration steps are:
|
||||
|
||||
1. Create a new project: https://console.developers.google.com/project
|
||||
|
||||
@ -3,6 +3,14 @@ id: keycloak_oidc
|
||||
title: Keycloak OIDC
|
||||
---
|
||||
|
||||
## Config Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ---------------- | --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ | ------- |
|
||||
| `--allowed-role` | `allowed_roles` | string \| list | restrict logins to users with this role (may be given multiple times). Only works with the keycloak-oidc provider. | |
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
--provider=keycloak-oidc
|
||||
--client-id=<your client's id>
|
||||
|
||||
15901
docs/package-lock.json
generated
15901
docs/package-lock.json
generated
File diff suppressed because it is too large
Load Diff
@ -22,6 +22,7 @@ const sidebars = {
|
||||
collapsed: false,
|
||||
items: [
|
||||
'configuration/overview',
|
||||
'configuration/integration',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'OAuth Provider Configuration',
|
||||
|
||||
270
docs/versioned_docs/version-7.6.x/configuration/integration.md
Normal file
270
docs/versioned_docs/version-7.6.x/configuration/integration.md
Normal file
@ -0,0 +1,270 @@
|
||||
---
|
||||
id: integration
|
||||
title: Integration
|
||||
---
|
||||
|
||||
## Configuring for use with the Nginx `auth_request` directive
|
||||
|
||||
**This option requires `--reverse-proxy` option to be set.**
|
||||
|
||||
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:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name ...;
|
||||
include ssl/ssl.conf;
|
||||
|
||||
location /oauth2/ {
|
||||
proxy_pass http://127.0.0.1:4180;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Auth-Request-Redirect $request_uri;
|
||||
# or, if you are handling multiple domains:
|
||||
# proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri;
|
||||
}
|
||||
location = /oauth2/auth {
|
||||
proxy_pass http://127.0.0.1:4180;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-Uri $request_uri;
|
||||
# nginx auth_request includes headers but not body
|
||||
proxy_set_header Content-Length "";
|
||||
proxy_pass_request_body off;
|
||||
}
|
||||
|
||||
location / {
|
||||
auth_request /oauth2/auth;
|
||||
error_page 401 =403 /oauth2/sign_in;
|
||||
|
||||
# pass information via X-User and X-Email headers to backend,
|
||||
# requires running with --set-xauthrequest flag
|
||||
auth_request_set $user $upstream_http_x_auth_request_user;
|
||||
auth_request_set $email $upstream_http_x_auth_request_email;
|
||||
proxy_set_header X-User $user;
|
||||
proxy_set_header X-Email $email;
|
||||
|
||||
# if you enabled --pass-access-token, this will pass the token to the backend
|
||||
auth_request_set $token $upstream_http_x_auth_request_access_token;
|
||||
proxy_set_header X-Access-Token $token;
|
||||
|
||||
# if you enabled --cookie-refresh, this is needed for it to work with auth_request
|
||||
auth_request_set $auth_cookie $upstream_http_set_cookie;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
|
||||
# When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb
|
||||
# limit and so the OAuth2 Proxy splits these into multiple parts.
|
||||
# Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,
|
||||
# so if your cookies are larger than 4kb, you will need to extract additional cookies manually.
|
||||
auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
|
||||
|
||||
# Extract the Cookie attributes from the first Set-Cookie header and append them
|
||||
# to the second part ($upstream_cookie_* variables only contain the raw cookie content)
|
||||
if ($auth_cookie ~* "(; .*)") {
|
||||
set $auth_cookie_name_0 $auth_cookie;
|
||||
set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
|
||||
}
|
||||
|
||||
# Send both Set-Cookie headers now if there was a second part
|
||||
if ($auth_cookie_name_upstream_1) {
|
||||
add_header Set-Cookie $auth_cookie_name_0;
|
||||
add_header Set-Cookie $auth_cookie_name_1;
|
||||
}
|
||||
|
||||
proxy_pass http://backend/;
|
||||
# or "root /path/to/site;" or "fastcgi_pass ..." etc
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When you use ingress-nginx in Kubernetes, you MUST use `kubernetes/ingress-nginx` (which includes the Lua module) and the following configuration snippet for your `Ingress`.
|
||||
Variables set with `auth_request_set` are not `set`-able in plain nginx config when the location is processed via `proxy_pass` and then may only be processed by Lua.
|
||||
Note that `nginxinc/kubernetes-ingress` does not include the Lua module.
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/auth-response-headers: Authorization
|
||||
nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$escaped_request_uri
|
||||
nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
|
||||
nginx.ingress.kubernetes.io/configuration-snippet: |
|
||||
auth_request_set $name_upstream_1 $upstream_cookie_name_1;
|
||||
|
||||
access_by_lua_block {
|
||||
if ngx.var.name_upstream_1 ~= "" then
|
||||
ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
|
||||
end
|
||||
}
|
||||
```
|
||||
It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
|
||||
|
||||
You have to substitute *name* 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=".
|
||||
|
||||
## Configuring for use with the Traefik (v2) `ForwardAuth` middleware
|
||||
|
||||
**This option requires `--reverse-proxy` option to be set.**
|
||||
|
||||
## ForwardAuth with 401 errors middleware
|
||||
|
||||
The [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) allows Traefik to authenticate requests via the oauth2-proxy's `/oauth2/auth` endpoint on every request, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the whole request through. For example, on Dynamic File (YAML) Configuration:
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
a-service:
|
||||
rule: "Host(`a-service.example.com`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-errors
|
||||
- oauth-auth
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
oauth:
|
||||
rule: "Host(`a-service.example.com`, `oauth.example.com`) && PathPrefix(`/oauth2/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
|
||||
services:
|
||||
a-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.2:7555
|
||||
oauth-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.1:4180
|
||||
|
||||
middlewares:
|
||||
auth-headers:
|
||||
headers:
|
||||
sslRedirect: true
|
||||
stsSeconds: 315360000
|
||||
browserXssFilter: true
|
||||
contentTypeNosniff: true
|
||||
forceSTSHeader: true
|
||||
sslHost: example.com
|
||||
stsIncludeSubdomains: true
|
||||
stsPreload: true
|
||||
frameDeny: true
|
||||
oauth-auth:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/oauth2/auth
|
||||
trustForwardHeader: true
|
||||
oauth-errors:
|
||||
errors:
|
||||
status:
|
||||
- "401-403"
|
||||
service: oauth-backend
|
||||
query: "/oauth2/sign_in?rd={url}"
|
||||
```
|
||||
|
||||
## ForwardAuth with static upstreams configuration
|
||||
|
||||
Redirect to sign_in functionality provided without the use of `errors` middleware with [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/http/forwardauth/) pointing to oauth2-proxy service's `/` endpoint
|
||||
|
||||
**Following options need to be set on `oauth2-proxy`:**
|
||||
- `--upstream=static://202`: Configures a static response for authenticated sessions
|
||||
- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
a-service-route-1:
|
||||
rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-auth-redirect # redirects all unauthenticated to oauth2 signin
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
a-service-route-2:
|
||||
rule: "Host(`a-service.example.com`) && PathPrefix(`/no-auto-redirect`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-auth-wo-redirect # unauthenticated session will return a 401
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
services-oauth2-route:
|
||||
rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/oauth2/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
oauth2-proxy-route:
|
||||
rule: "Host(`oauth.example.com`) && PathPrefix(`/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
|
||||
services:
|
||||
a-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.2:7555
|
||||
b-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.3:7555
|
||||
oauth-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.1:4180
|
||||
|
||||
middlewares:
|
||||
auth-headers:
|
||||
headers:
|
||||
sslRedirect: true
|
||||
stsSeconds: 315360000
|
||||
browserXssFilter: true
|
||||
contentTypeNosniff: true
|
||||
forceSTSHeader: true
|
||||
sslHost: example.com
|
||||
stsIncludeSubdomains: true
|
||||
stsPreload: true
|
||||
frameDeny: true
|
||||
oauth-auth-redirect:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/
|
||||
trustForwardHeader: true
|
||||
authResponseHeaders:
|
||||
- X-Auth-Request-Access-Token
|
||||
- Authorization
|
||||
oauth-auth-wo-redirect:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/oauth2/auth
|
||||
trustForwardHeader: true
|
||||
authResponseHeaders:
|
||||
- X-Auth-Request-Access-Token
|
||||
- Authorization
|
||||
```
|
||||
|
||||
:::note
|
||||
If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
|
||||
:::
|
||||
@ -5,7 +5,7 @@ title: Overview
|
||||
|
||||
`oauth2-proxy` can be configured via [command line options](#command-line-options), [environment variables](#environment-variables) or [config file](#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
|
||||
## Generating a Cookie Secret
|
||||
|
||||
To generate a strong cookie secret use one of the below commands:
|
||||
|
||||
@ -56,167 +56,208 @@ import TabItem from '@theme/TabItem';
|
||||
</TabItem>
|
||||
</Tabs>
|
||||
|
||||
### Config File
|
||||
## 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](https://github.com/oauth2-proxy/oauth2-proxy/blob/master/contrib/oauth2-proxy.cfg.example) config file is in the contrib directory. It can be used by specifying `--config=/etc/oauth2-proxy.cfg`
|
||||
|
||||
## Config Options
|
||||
|
||||
### Command Line Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ---------------------------------------------- | -------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| `--acr-values` | `acr_values` | string | optional, see [docs](https://openid.net/specs/openid-connect-eap-acr-values-1_0.html#acrValues) | `""` |
|
||||
| `--allow-query-semicolons` | `allow_query_semicolons` | bool | allow the use of semicolons in query args ([required for some legacy applications](https://github.com/golang/go/issues/25192)) | `false` |
|
||||
| `--api-route` | `api_routes` | string \| list | return HTTP 401 instead of redirecting to authentication server if token is not valid. Format: path_regex | |
|
||||
| `--approval-prompt` | `approval_prompt` | string | OAuth approval_prompt | `"force"` |
|
||||
| `--auth-logging` | `auth_logging` | bool | Log authentication attempts | true |
|
||||
| `--auth-logging-format` | `auth_logging_format` | string | Template for authentication log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| `--authenticated-emails-file` | `authenticated_emails_file` | string | authenticate against emails via file (one per line) | |
|
||||
| `--azure-tenant` | `azure_tenant` | string | go to a tenant-specific or common (tenant-independent) endpoint. | `"common"` |
|
||||
| `--backend-logout-url` | `backend_logout_url` | string | URL to perform backend logout, if you use `{id_token}` in the url it will be replaced by the actual `id_token` of the user session | |
|
||||
| `--basic-auth-password` | `basic_auth_password` | string | the password to set when passing the HTTP Basic Auth header | |
|
||||
| `--client-id` | `client_id` | string | the OAuth Client ID, e.g. `"123456.apps.googleusercontent.com"` | |
|
||||
| `--client-secret` | `client_secret` | string | the OAuth Client Secret | |
|
||||
| `--client-secret-file` | `client_secret_file` | string | the file with OAuth Client Secret | |
|
||||
| `--code-challenge-method` | `code_challenge_method` | string | use PKCE code challenges with the specified method. Either 'plain' or 'S256' (recommended) | |
|
||||
| `--config` | --- | string | path to config file | |
|
||||
| `--cookie-domain` | `cookie_domains` | string \| list | Optional cookie domains to force cookies to (e.g. `.yourcompany.com`). The longest domain matching the request's host will be used (or the shortest cookie domain if there is no match). | |
|
||||
| `--cookie-expire` | `cookie_expire` | duration | expire timeframe for cookie. If set to 0, cookie becomes a session-cookie which will expire when the browser is closed. | 168h0m0s |
|
||||
| `--cookie-httponly` | `cookie_httponly` | bool | set HttpOnly cookie flag | true |
|
||||
| `--cookie-name` | `cookie_name` | string | the name of the cookie that the oauth_proxy creates. Should be changed to use a [cookie prefix](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes) (`__Host-` or `__Secure-`) if `--cookie-secure` is set. | `"_oauth2_proxy"` |
|
||||
| `--cookie-path` | `cookie_path` | string | an optional cookie path to force cookies to (e.g. `/poc/`) | `"/"` |
|
||||
| `--cookie-refresh` | `cookie_refresh` | duration | refresh the cookie after this duration; `0` to disable; not supported by all providers [^1] | |
|
||||
| `--cookie-secret` | `cookie_secret` | string | the seed string for secure cookies (optionally base64 encoded) | |
|
||||
| `--cookie-secure` | `cookie_secure` | bool | set [secure (HTTPS only) cookie flag](https://owasp.org/www-community/controls/SecureFlag) | true |
|
||||
| `--cookie-samesite` | `cookie_samesite` | string | set SameSite cookie attribute (`"lax"`, `"strict"`, `"none"`, or `""`). | `""` |
|
||||
| `--cookie-csrf-per-request` | `cookie_csrf_per_request` | bool | Enable having different CSRF cookies per request, making it possible to have parallel requests. | false |
|
||||
| `--cookie-csrf-expire` | `cookie_csrf_expire` | duration | expire timeframe for CSRF cookie | 15m |
|
||||
| `--custom-templates-dir` | `custom_templates_dir` | string | path to custom html templates | |
|
||||
| `--custom-sign-in-logo` | `custom_sign_in_logo` | string | path or a URL to an custom image for the sign_in page logo. Use `"-"` to disable default logo. |
|
||||
| `--display-htpasswd-form` | `display_htpasswd_form` | bool | display username / password login form if an htpasswd file is provided | true |
|
||||
| `--email-domain` | `email_domains` | string \| list | authenticate emails with the specified domain (may be given multiple times). Use `*` to authenticate any email | |
|
||||
| `--errors-to-info-log` | `errors_to_info_log` | bool | redirects error-level logging to default log channel instead of stderr | false |
|
||||
| `--extra-jwt-issuers` | `extra_jwt_issuers` | string | if `--skip-jwt-bearer-tokens` is set, a list of extra JWT `issuer=audience` (see a token's `iss`, `aud` fields) pairs (where the issuer URL has a `.well-known/openid-configuration` or a `.well-known/jwks.json`) | |
|
||||
| `--exclude-logging-path` | `exclude_logging_paths` | string | comma separated list of paths to exclude from logging, e.g. `"/ping,/path2"` | `""` (no paths excluded) |
|
||||
| `--flush-interval` | `flush_interval` | duration | period between flushing response buffers when streaming responses | `"1s"` |
|
||||
| `--force-https` | `force_https` | bool | enforce https redirect | `false` |
|
||||
| `--force-json-errors` | `force_json_errors` | bool | force JSON errors instead of HTTP error pages or redirects | `false` |
|
||||
| `--banner` | `banner` | string | custom (html) banner string. Use `"-"` to disable default banner. | |
|
||||
| `--footer` | `footer` | string | custom (html) footer string. Use `"-"` to disable default footer. | |
|
||||
| `--github-org` | `github_org` | string | restrict logins to members of this organisation | |
|
||||
| `--github-team` | `github_team` | string | restrict logins to members of any of these teams (slug), separated by a comma | |
|
||||
| `--github-repo` | `github_repo` | string | restrict logins to collaborators of this repository formatted as `orgname/repo` | |
|
||||
| `--github-token` | `github_token` | string | the token to use when verifying repository collaborators (must have push access to the repository) | |
|
||||
| `--github-user` | `github_users` | string \| list | To allow users to login by username even if they do not belong to the specified org and team or collaborators | |
|
||||
| `--gitlab-group` | `gitlab_groups` | string \| list | restrict logins to members of any of these groups (slug), separated by a comma | |
|
||||
| `--gitlab-projects` | `gitlab_projects` | string \| list | restrict logins to members of any of these projects (may be given multiple times) formatted as `orgname/repo=accesslevel`. Access level should be a value matching [Gitlab access levels](https://docs.gitlab.com/ee/api/members.html#valid-access-levels), defaulted to 20 if absent | |
|
||||
| `--google-admin-email` | `google_admin_email` | string | the google admin to impersonate for api calls | |
|
||||
| `--google-group` | `google_groups` | string | restrict logins to members of this google group (may be given multiple times). | |
|
||||
| `--google-service-account-json` | `google_service_account_json` | string | the path to the service account json credentials | |
|
||||
| `--google-use-application-default-credentials` | `google_use_application_default_credentials` | bool | use application default credentials instead of service account json (i.e. GKE Workload Identity) | |
|
||||
| `--google-target-principal` | `google_target_principal` | bool | the target principal to impersonate when using ADC | defaults to the service account configured for ADC |
|
||||
| `--htpasswd-file` | `htpasswd_file` | string | additionally authenticate against a htpasswd file. Entries must be created with `htpasswd -B` for bcrypt encryption | |
|
||||
| `--htpasswd-user-group` | `htpasswd_user_groups` | string \| list | the groups to be set on sessions for htpasswd users | |
|
||||
| `--http-address` | `http_address` | string | `[http://]<addr>:<port>` or `unix://<path>` to listen on for HTTP clients. Square brackets are required for ipv6 address, e.g. `http://[::1]:4180` | `"127.0.0.1:4180"` |
|
||||
| `--https-address` | `https_address` | string | `[https://]<addr>:<port>` to listen on for HTTPS clients. Square brackets are required for ipv6 address, e.g. `https://[::1]:443` | `":443"` |
|
||||
| `--logging-compress` | `logging_compress` | bool | Should rotated log files be compressed using gzip | false |
|
||||
| `--logging-filename` | `logging_filename` | string | File to log requests to, empty for `stdout` | `""` (stdout) |
|
||||
| `--logging-local-time` | `logging_local_time` | bool | Use local time in log files and backup filenames instead of UTC | true (local time) |
|
||||
| `--logging-max-age` | `logging_max_age` | int | Maximum number of days to retain old log files | 7 |
|
||||
| `--logging-max-backups` | `logging_max_backups` | int | Maximum number of old log files to retain; 0 to disable | 0 |
|
||||
| `--logging-max-size` | `logging_max_size` | int | Maximum size in megabytes of the log file before rotation | 100 |
|
||||
| `--jwt-key` | `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 | |
|
||||
| `--jwt-key-file` | `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 | |
|
||||
| `--login-url` | `login_url` | string | Authentication endpoint | |
|
||||
| `--insecure-oidc-allow-unverified-email` | `insecure_oidc_allow_unverified_email` | bool | don't fail if an email address in an id_token is not verified | false |
|
||||
| `--insecure-oidc-skip-issuer-verification` | `insecure_oidc_skip_issuer_verification` | bool | allow the OIDC issuer URL to differ from the expected (currently required for Azure multi-tenant compatibility) | false |
|
||||
| `--insecure-oidc-skip-nonce` | `insecure_oidc_skip_nonce` | bool | skip verifying the OIDC ID Token's nonce claim | true |
|
||||
| `--oidc-issuer-url` | `oidc_issuer_url` | string | the OpenID Connect issuer URL, e.g. `"https://accounts.google.com"` | |
|
||||
| `--oidc-jwks-url` | `oidc_jwks_url` | string | OIDC JWKS URI for token verification; required if OIDC discovery is disabled | |
|
||||
| `--oidc-email-claim` | `oidc_email_claim` | string | which OIDC claim contains the user's email | `"email"` |
|
||||
| `--oidc-groups-claim` | `oidc_groups_claim` | string | which OIDC claim contains the user groups | `"groups"` |
|
||||
| `--oidc-audience-claim` | `oidc_audience_claims` | string | which OIDC claim contains the audience | `"aud"` |
|
||||
| `--oidc-extra-audience` | `oidc_extra_audiences` | string \| list | additional audiences which are allowed to pass verification | `"[]"` |
|
||||
| `--pass-access-token` | `pass_access_token` | bool | pass OAuth access_token to upstream via X-Forwarded-Access-Token header. When used with `--set-xauthrequest` this adds the X-Auth-Request-Access-Token header to the response | false |
|
||||
| `--pass-authorization-header` | `pass_authorization_header` | bool | pass OIDC IDToken to upstream via Authorization Bearer header | false |
|
||||
| `--pass-basic-auth` | `pass_basic_auth` | bool | pass HTTP Basic Auth, X-Forwarded-User, X-Forwarded-Email and X-Forwarded-Preferred-Username information to upstream | true |
|
||||
| `--prefer-email-to-user` | `prefer_email_to_user` | bool | Prefer to use the Email address as the Username when passing information to upstream. Will only use Username if Email is unavailable, e.g. htaccess authentication. Used in conjunction with `--pass-basic-auth` and `--pass-user-headers` | false |
|
||||
| `--pass-host-header` | `pass_host_header` | bool | pass the request Host Header to upstream | true |
|
||||
| `--pass-user-headers` | `pass_user_headers` | bool | pass X-Forwarded-User, X-Forwarded-Groups, X-Forwarded-Email and X-Forwarded-Preferred-Username information to upstream | true |
|
||||
| `--profile-url` | `profile_url` | string | Profile access endpoint | |
|
||||
| `--skip-claims-from-profile-url` | `skip_claims_from_profile_url` | bool | skip request to Profile URL for resolving claims not present in id_token | false |
|
||||
| `--prompt` | `prompt` | string | [OIDC prompt](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest); if present, `approval-prompt` is ignored | `""` |
|
||||
| `--provider` | `provider` | string | OAuth provider | google |
|
||||
| `--provider-ca-file` | `provider_ca_file` | string \| list | Paths to CA certificates that should be used when connecting to the provider. If not specified, the default Go trust sources are used instead. |
|
||||
| `--use-system-trust-store` | `use_system_trust_store` | bool | Determines if `provider-ca-file` files and the system trust store are used. If set to true, your custom CA files and the system trust store are used otherwise only your custom CA files. | false |
|
||||
| `--provider-display-name` | `provider_display_name` | string | Override the provider's name with the given string; used for the sign-in page | (depends on provider) |
|
||||
| `--ping-path` | `ping_path` | string | the ping endpoint that can be used for basic health checks | `"/ping"` |
|
||||
| `--ping-user-agent` | `ping_user_agent` | string | a User-Agent that can be used for basic health checks | `""` (don't check user agent) |
|
||||
| `--ready-path` | `ready_path` | string | the ready endpoint that can be used for deep health checks | `"/ready"` |
|
||||
| `--metrics-address` | `metrics_address` | string | the address prometheus metrics will be scraped from | `""` |
|
||||
| `--proxy-prefix` | `proxy_prefix` | string | the url root path that this proxy should be nested under (e.g. /`<oauth2>/sign_in`) | `"/oauth2"` |
|
||||
| `--proxy-websockets` | `proxy_websockets` | bool | enables WebSocket proxying | true |
|
||||
| `--pubjwk-url` | `pubjwk_url` | string | JWK pubkey access endpoint: required by login.gov | |
|
||||
| `--real-client-ip-header` | `real_client_ip_header` | string | Header used to determine the real IP of the client, requires `--reverse-proxy` to be set (one of: X-Forwarded-For, X-Real-IP, or X-ProxyUser-IP) | X-Real-IP |
|
||||
| `--redeem-url` | `redeem_url` | string | Token redemption endpoint | |
|
||||
| `--redirect-url` | `redirect_url` | string | the OAuth Redirect URL, e.g. `"https://internalapp.yourcompany.com/oauth2/callback"` | |
|
||||
| `--relative-redirect-url` | `relative_redirect_url` | bool | allow relative OAuth Redirect URL.` | false |
|
||||
| `--redis-cluster-connection-urls` | `redis_cluster_connection_urls` | string \| list | List of Redis cluster connection URLs (e.g. `redis://HOST[:PORT]`). Used in conjunction with `--redis-use-cluster` | |
|
||||
| `--redis-connection-url` | `redis_connection_url` | string | URL of redis server for redis session storage (e.g. `redis://HOST[:PORT]`) | |
|
||||
| `--redis-insecure-skip-tls-verify` | `redis_insecure_skip_tls_verify` | bool | skip TLS verification when connecting to Redis | false |
|
||||
| `--redis-password` | `redis_password` | string | Redis password. Applicable for all Redis configurations. Will override any password set in `--redis-connection-url` | |
|
||||
| `--redis-sentinel-password` | `redis_sentinel_password` | string | Redis sentinel password. Used only for sentinel connection; any redis node passwords need to use `--redis-password` | |
|
||||
| `--redis-sentinel-master-name` | `redis_sentinel_master_name` | string | Redis sentinel master name. Used in conjunction with `--redis-use-sentinel` | |
|
||||
| `--redis-sentinel-connection-urls` | `redis_sentinel_connection_urls` | string \| list | List of Redis sentinel connection URLs (e.g. `redis://HOST[:PORT]`). Used in conjunction with `--redis-use-sentinel` | |
|
||||
| `--redis-use-cluster` | `redis_use_cluster` | bool | Connect to redis cluster. Must set `--redis-cluster-connection-urls` to use this feature | false |
|
||||
| `--redis-use-sentinel` | `redis_use_sentinel` | bool | Connect to redis via sentinels. Must set `--redis-sentinel-master-name` and `--redis-sentinel-connection-urls` to use this feature | false |
|
||||
| `--redis-connection-idle-timeout` | `redis_connection_idle_timeout` | int | Redis connection idle timeout seconds. If Redis [timeout](https://redis.io/docs/reference/clients/#client-timeouts) option is set to non-zero, the `--redis-connection-idle-timeout` must be less than Redis timeout option. Example: if either redis.conf includes `timeout 15` or using `CONFIG SET timeout 15` the `--redis-connection-idle-timeout` must be at least `--redis-connection-idle-timeout=14` | 0 |
|
||||
| `--request-id-header` | `request_id_header` | string | Request header to use as the request ID in logging | X-Request-Id |
|
||||
| `--request-logging` | `request_logging` | bool | Log requests | true |
|
||||
| `--request-logging-format` | `request_logging_format` | string | Template for request log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| `--resource` | `resource` | string | The resource that is protected (Azure AD only) | |
|
||||
| `--reverse-proxy` | `reverse_proxy` | bool | are we running behind a reverse proxy, controls whether headers like X-Real-IP are accepted and allows X-Forwarded-\{Proto,Host,Uri\} headers to be used on redirect selection | false |
|
||||
| `--scope` | `scope` | string | OAuth scope specification | |
|
||||
| `--session-cookie-minimal` | `session_cookie_minimal` | bool | strip OAuth tokens from cookie session stores if they aren't needed (cookie session store only) | false |
|
||||
| `--session-store-type` | `session_store_type` | string | [Session data storage backend](sessions.md); redis or cookie | cookie |
|
||||
| `--set-xauthrequest` | `set_xauthrequest` | bool | set X-Auth-Request-User, X-Auth-Request-Groups, X-Auth-Request-Email and X-Auth-Request-Preferred-Username response headers (useful in Nginx auth_request mode). When used with `--pass-access-token`, X-Auth-Request-Access-Token is added to response headers. | false |
|
||||
| `--set-authorization-header` | `set_authorization_header` | bool | set Authorization Bearer response header (useful in Nginx auth_request mode) | false |
|
||||
| `--set-basic-auth` | `set_basic_auth` | bool | set HTTP Basic Auth information in response (useful in Nginx auth_request mode) | false |
|
||||
| `--show-debug-on-error` | `show_debug_on_error` | bool | show detailed error information on error pages (WARNING: this may contain sensitive information - do not use in production) | false |
|
||||
| `--signature-key` | `signature_key` | string | GAP-Signature request signature key (algorithm:secretkey) | |
|
||||
| `--silence-ping-logging` | `silence_ping_logging` | bool | disable logging of requests to ping & ready endpoints | false |
|
||||
| `--skip-auth-preflight` | `skip_auth_preflight` | bool | will skip authentication for OPTIONS requests | false |
|
||||
| `--skip-auth-regex` | `skip_auth_regex` | string \| list | (DEPRECATED for `--skip-auth-route`) bypass authentication for requests paths that match (may be given multiple times) | |
|
||||
| `--skip-auth-route` | `skip_auth_routes` | string \| list | bypass authentication for requests that match the method & path. Format: method=path_regex OR method!=path_regex. For all methods: path_regex OR !=path_regex | |
|
||||
| `--skip-auth-strip-headers` | `skip_auth_strip_headers` | bool | strips `X-Forwarded-*` style authentication headers & `Authorization` header if they would be set by oauth2-proxy | true |
|
||||
| `--skip-jwt-bearer-tokens` | `skip_jwt_bearer_tokens` | bool | will skip requests that have verified JWT bearer tokens (the token must have [`aud`](https://en.wikipedia.org/wiki/JSON_Web_Token#Standard_fields) that matches this client id or one of the extras from `extra-jwt-issuers`) | false |
|
||||
| `--skip-oidc-discovery` | `skip_oidc_discovery` | bool | bypass OIDC endpoint discovery. `--login-url`, `--redeem-url` and `--oidc-jwks-url` must be configured in this case | false |
|
||||
| `--skip-provider-button` | `skip_provider_button` | bool | will skip sign-in-page to directly reach the next step: oauth/start | false |
|
||||
| `--ssl-insecure-skip-verify` | `ssl_insecure_skip_verify` | bool | skip validation of certificates presented when using HTTPS providers | false |
|
||||
| `--ssl-upstream-insecure-skip-verify` | `ssl_upstream_insecure_skip_verify` | bool | skip validation of certificates presented when using HTTPS upstreams | false |
|
||||
| `--standard-logging` | `standard_logging` | bool | Log standard runtime information | true |
|
||||
| `--standard-logging-format` | `standard_logging_format` | string | Template for standard log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| `--tls-cert-file` | `tls_cert_file` | string | path to certificate file | |
|
||||
| `--tls-cipher-suite` | `tls_cipher_suites` | string \| list | Restricts TLS cipher suites used by server to those listed (e.g. TLS_RSA_WITH_RC4_128_SHA) (may be given multiple times). If not specified, the default Go safe cipher list is used. List of valid cipher suites can be found in the [crypto/tls documentation](https://pkg.go.dev/crypto/tls#pkg-constants). | |
|
||||
| `--tls-key-file` | `tls_key_file` | string | path to private key file | |
|
||||
| `--tls-min-version` | `tls_min_version` | string | minimum TLS version that is acceptable, either `"TLS1.2"` or `"TLS1.3"` | `"TLS1.2"` |
|
||||
| `--upstream` | `upstreams` | string \| list | the http url(s) of the upstream endpoint, file:// paths for static files or `static://<status_code>` for static response. Routing is based on the path | |
|
||||
| `--upstream-timeout` | `upstream_timeout` | duration | maximum amount of time the server will wait for a response from the upstream | 30s |
|
||||
| `--allowed-group` | `allowed_groups` | string \| list | restrict logins to members of this group (may be given multiple times) | |
|
||||
| `--allowed-role` | `allowed_roles` | string \| list | restrict logins to users with this role (may be given multiple times). Only works with the keycloak-oidc provider. | |
|
||||
| `--validate-url` | `validate_url` | string | Access token validation endpoint | |
|
||||
| `--version` | --- | n/a | print version string | |
|
||||
| `--whitelist-domain` | `whitelist_domains` | string \| list | allowed domains for redirection after authentication. Prefix domain with a `.` or a `*.` to allow subdomains (e.g. `.example.com`, `*.example.com`) [^2] | |
|
||||
| `--trusted-ip` | `trusted_ips` | string \| list | list of IPs or CIDR ranges to allow to bypass authentication (may be given multiple times). When combined with `--reverse-proxy` and optionally `__real_client_ip_header` this will evaluate the trust of the IP stored in an HTTP header by a reverse proxy rather than the layer-3/4 remote address. WARNING: trusting IPs has inherent security flaws, especially when obtaining the IP address from an HTTP header (reverse-proxy mode). Use this option only if you understand the risks and how to manage them. | |
|
||||
| `--encode-state` | `encode_state` | bool | encode the state parameter as UrlEncodedBase64 | false |
|
||||
| Flag | Description |
|
||||
| ----------- | -------------------- |
|
||||
| `--config` | path to config file |
|
||||
| `--version` | print version string |
|
||||
|
||||
[^1]: Only these providers support `--cookie-refresh`: GitLab, Google and OIDC
|
||||
[^2]: When using the `whitelist-domain` option, any domain prefixed with a `.` or a `*.` will allow any subdomain of the specified domain as a valid redirect URL. By default, only empty ports are allowed. This translates to allowing the default port of the URLs protocol (80 for HTTP, 443 for HTTPS, etc.) since browsers omit them. To allow only a specific port, add it to the whitelisted domain: `example.com:8080`. To allow any port, use `*`: `example.com:*`.
|
||||
### General Provider Options
|
||||
|
||||
See below for provider specific options
|
||||
Provider specific options can be found on their respective subpages.
|
||||
|
||||
### Upstreams Configuration
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| --------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
||||
| flag: `--acr-values`<br/>toml: `acr_values` | string | optional, see [docs](https://openid.net/specs/openid-connect-eap-acr-values-1_0.html#acrValues) | `""` |
|
||||
| flag: `--allowed-group`<br/>toml: `allowed_groups` | string \| list | restrict logins to members of this group (may be given multiple times) | |
|
||||
| flag: `--approval-prompt`<br/>toml: `approval_prompt` | string | OAuth approval_prompt | `"force"` |
|
||||
| flag: `--backend-logout-url`<br/>toml: `backend_logout_url` | string | URL to perform backend logout, if you use `{id_token}` in the url it will be replaced by the actual `id_token` of the user session | |
|
||||
| flag: `--client-id`<br/>toml: `client_id` | string | the OAuth Client ID, e.g. `"123456.apps.googleusercontent.com"` | |
|
||||
| flag: `--client-secret-file`<br/>toml: `client_secret_file` | string | the file with OAuth Client Secret | |
|
||||
| flag: `--client-secret`<br/>toml: `client_secret` | string | the OAuth Client Secret | |
|
||||
| flag: `--code-challenge-method`<br/>toml: `code_challenge_method` | string | use PKCE code challenges with the specified method. Either 'plain' or 'S256' (recommended) | |
|
||||
| flag: `--insecure-oidc-allow-unverified-email`<br/>toml: `insecure_oidc_allow_unverified_email` | bool | don't fail if an email address in an id_token is not verified | false |
|
||||
| flag: `--insecure-oidc-skip-issuer-verification`<br/>toml: `insecure_oidc_skip_issuer_verification` | bool | allow the OIDC issuer URL to differ from the expected (currently required for Azure multi-tenant compatibility) | false |
|
||||
| flag: `--insecure-oidc-skip-nonce`<br/>toml: `insecure_oidc_skip_nonce` | bool | skip verifying the OIDC ID Token's nonce claim | true |
|
||||
| flag: `--jwt-key-file`<br/>toml: `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 | |
|
||||
| flag: `--jwt-key`<br/>toml: `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 | |
|
||||
| flag: `--login-url`<br/>toml: `login_url` | string | Authentication endpoint | |
|
||||
| flag: `--oidc-audience-claim`<br/>toml: `oidc_audience_claims` | string | which OIDC claim contains the audience | `"aud"` |
|
||||
| flag: `--oidc-email-claim`<br/>toml: `oidc_email_claim` | string | which OIDC claim contains the user's email | `"email"` |
|
||||
| flag: `--oidc-extra-audience`<br/>toml: `oidc_extra_audiences` | string \| list | additional audiences which are allowed to pass verification | `"[]"` |
|
||||
| flag: `--oidc-groups-claim`<br/>toml: `oidc_groups_claim` | string | which OIDC claim contains the user groups | `"groups"` |
|
||||
| flag: `--oidc-issuer-url`<br/>toml: `oidc_issuer_url` | string | the OpenID Connect issuer URL, e.g. `"https://accounts.google.com"` | |
|
||||
| flag: `--oidc-jwks-url`<br/>toml: `oidc_jwks_url` | string | OIDC JWKS URI for token verification; required if OIDC discovery is disabled | |
|
||||
| flag: `--profile-url`<br/>toml: `profile_url` | string | Profile access endpoint | |
|
||||
| flag: `--prompt`<br/>toml: `prompt` | string | [OIDC prompt](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest); if present, `approval-prompt` is ignored | `""` |
|
||||
| flag: `--provider-ca-file`<br/>toml: `provider_ca_file` | string \| list | Paths to CA certificates that should be used when connecting to the provider. If not specified, the default Go trust sources are used instead. |
|
||||
| flag: `--provider-display-name`<br/>toml: `provider_display_name` | string | Override the provider's name with the given string; used for the sign-in page | (depends on provider) |
|
||||
| flag: `--provider`<br/>toml: `provider` | string | OAuth provider | google |
|
||||
| flag: `--pubjwk-url`<br/>toml: `pubjwk_url` | string | JWK pubkey access endpoint: required by login.gov | |
|
||||
| flag: `--redeem-url`<br/>toml: `redeem_url` | string | Token redemption endpoint | |
|
||||
| flag: `--scope`<br/>toml:`scope` | string | OAuth scope specification | |
|
||||
| flag: `--skip-claims-from-profile-url`<br/>toml: `skip_claims_from_profile_url` | bool | skip request to Profile URL for resolving claims not present in id_token | false |
|
||||
| flag: `--skip-oidc-discovery`<br/>toml: `skip_oidc_discovery` | bool | bypass OIDC endpoint discovery. `--login-url`, `--redeem-url` and `--oidc-jwks-url` must be configured in this case | false |
|
||||
| flag: `--use-system-trust-store`<br/>toml: `use_system_trust_store` | bool | Determines if `provider-ca-file` files and the system trust store are used. If set to true, your custom CA files and the system trust store are used otherwise only your custom CA files. | false |
|
||||
| flag: `--validate-url`<br/>toml: `validate_url` | string | Access token validation endpoint | |
|
||||
|
||||
### Cookie Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| -------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
|
||||
| flag: `--cookie-csrf-expire`<br/>toml: `cookie_csrf_expire` | duration | expire timeframe for CSRF cookie | 15m |
|
||||
| flag: `--cookie-csrf-per-request`<br/>toml:`cookie_csrf_per_request` | bool | Enable having different CSRF cookies per request, making it possible to have parallel requests. | false |
|
||||
| flag: `--cookie-domain`<br/>toml: `cookie_domains` | string \| list | Optional cookie domains to force cookies to (e.g. `.yourcompany.com`). The longest domain matching the request's host will be used (or the shortest cookie domain if there is no match). | |
|
||||
| flag: `--cookie-expire`<br/>toml: `cookie_expire` | duration | expire timeframe for cookie. If set to 0, cookie becomes a session-cookie which will expire when the browser is closed. | 168h0m0s |
|
||||
| flag: `--cookie-httponly`<br/>toml: `cookie_httponly` | bool | set HttpOnly cookie flag | true |
|
||||
| flag: `--cookie-name`<br/>toml: `cookie_name` | string | the name of the cookie that the oauth_proxy creates. Should be changed to use a [cookie prefix](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#cookie_prefixes) (`__Host-` or `__Secure-`) if `--cookie-secure` is set. | `"_oauth2_proxy"` |
|
||||
| flag: `--cookie-path`<br/>toml: `cookie_path` | string | an optional cookie path to force cookies to (e.g. `/poc/`) | `"/"` |
|
||||
| flag: `--cookie-refresh`<br/>toml: `cookie_refresh` | duration | refresh the cookie after this duration; `0` to disable; not supported by all providers [^1] | |
|
||||
| flag: `--cookie-samesite`<br/>toml: `cookie_samesite` | string | set SameSite cookie attribute (`"lax"`, `"strict"`, `"none"`, or `""`). | `""` |
|
||||
| flag: `--cookie-secret`<br/>toml: `cookie_secret` | string | the seed string for secure cookies (optionally base64 encoded) | |
|
||||
| flag: `--cookie-secure`<br/>toml: `cookie_secure` | bool | set [secure (HTTPS only) cookie flag](https://owasp.org/www-community/controls/SecureFlag) | true |
|
||||
|
||||
[^1]: The following providers support `--cookie-refresh`: ADFS, Azure, GitLab, Google, Keycloak and all other Identity Providers which support the full [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens)
|
||||
|
||||
### Header Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| flag: `--basic-auth-password`<br/>toml: `basic_auth_password` | string | the password to set when passing the HTTP Basic Auth header | |
|
||||
| flag: `--set-xauthrequest`<br/>toml: `set_xauthrequest` | bool | set X-Auth-Request-User, X-Auth-Request-Groups, X-Auth-Request-Email and X-Auth-Request-Preferred-Username response headers (useful in Nginx auth_request mode). When used with `--pass-access-token`, X-Auth-Request-Access-Token is added to response headers. | false |
|
||||
| flag: `--set-authorization-header`<br/>toml: `set_authorization_header` | bool | set Authorization Bearer response header (useful in Nginx auth_request mode) | false |
|
||||
| flag: `--set-basic-auth`<br/>toml: `set_basic_auth` | bool | set HTTP Basic Auth information in response (useful in Nginx auth_request mode) | false |
|
||||
| flag: `--skip-auth-strip-headers`<br/>toml: `skip_auth_strip_headers` | bool | strips `X-Forwarded-*` style authentication headers & `Authorization` header if they would be set by oauth2-proxy | true |
|
||||
| flag: `--pass-access-token`<br/>toml: `pass_access_token` | bool | pass OAuth access_token to upstream via X-Forwarded-Access-Token header. When used with `--set-xauthrequest` this adds the X-Auth-Request-Access-Token header to the response | false |
|
||||
| flag: `--pass-authorization-header`<br/>toml: `pass_authorization_header` | bool | pass OIDC IDToken to upstream via Authorization Bearer header | false |
|
||||
| flag: `--pass-basic-auth`<br/>toml: `pass_basic_auth` | bool | pass HTTP Basic Auth, X-Forwarded-User, X-Forwarded-Email and X-Forwarded-Preferred-Username information to upstream | true |
|
||||
| flag: `--prefer-email-to-user`<br/>toml: `prefer_email_to_user` | bool | Prefer to use the Email address as the Username when passing information to upstream. Will only use Username if Email is unavailable, e.g. htaccess authentication. Used in conjunction with `--pass-basic-auth` and `--pass-user-headers` | false |
|
||||
| flag: `--pass-user-headers`<br/>toml: `pass_user_headers` | bool | pass X-Forwarded-User, X-Forwarded-Groups, X-Forwarded-Email and X-Forwarded-Preferred-Username information to upstream | true |
|
||||
|
||||
### Logging Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| --------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------- | --------------------------------------------------- |
|
||||
| flag: `--auth-logging-format`<br/>toml: `auth_logging_format` | string | Template for authentication log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| flag: `--auth-logging`<br/>toml: `auth_logging` | bool | Log authentication attempts | true |
|
||||
| flag: `--errors-to-info-log`<br/>toml: `errors_to_info_log` | bool | redirects error-level logging to default log channel instead of stderr | false |
|
||||
| flag: `--exclude-logging-path`<br/>toml: `exclude_logging_paths` | string | comma separated list of paths to exclude from logging, e.g. `"/ping,/path2"` | `""` (no paths excluded) |
|
||||
| flag: `--logging-compress`<br/>toml: `logging_compress` | bool | Should rotated log files be compressed using gzip | false |
|
||||
| flag: `--logging-filename`<br/>toml: `logging_filename` | string | File to log requests to, empty for `stdout` | `""` (stdout) |
|
||||
| flag: `--logging-local-time`<br/>toml: `logging_local_time` | bool | Use local time in log files and backup filenames instead of UTC | true (local time) |
|
||||
| flag: `--logging-max-age`<br/>toml: `logging_max_age` | int | Maximum number of days to retain old log files | 7 |
|
||||
| flag: `--logging-max-backups`<br/>toml: `logging_max_backups` | int | Maximum number of old log files to retain; 0 to disable | 0 |
|
||||
| flag: `--logging-max-size`<br/>toml: `logging_max_size` | int | Maximum size in megabytes of the log file before rotation | 100 |
|
||||
| flag: `--request-id-header`<br/>toml: `request_id_header` | string | Request header to use as the request ID in logging | X-Request-Id |
|
||||
| flag: `--request-logging-format`<br/>toml: `request_logging_format` | string | Template for request log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| flag: `--request-logging`<br/>toml: `request_logging` | bool | Log requests | true |
|
||||
| flag: `--silence-ping-logging`<br/>toml: `silence_ping_logging` | bool | disable logging of requests to ping & ready endpoints | false |
|
||||
| flag: `--standard-logging-format`<br/>toml: `standard_logging_format` | string | Template for standard log lines | see [Logging Configuration](#logging-configuration) |
|
||||
| flag: `--standard-logging`<br/>toml: `standard_logging` | bool | Log standard runtime information | true |
|
||||
|
||||
### Page Template Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ----------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| flag: `--banner`<br/>toml: `banner` | string | custom (html) banner string. Use `"-"` to disable default banner. | |
|
||||
| flag: `--custom-sign-in-logo`<br/>toml: `custom_sign_in_logo` | string | path or a URL to an custom image for the sign_in page logo. Use `"-"` to disable default logo. |
|
||||
| flag: `--custom-templates-dir`<br/>toml: `custom_templates_dir` | string | path to custom html templates | |
|
||||
| flag: `--display-htpasswd-form`<br/>toml: `display_htpasswd_form` | bool | display username / password login form if an htpasswd file is provided | true |
|
||||
| flag: `--footer`<br/>toml: `footer` | string | custom (html) footer string. Use `"-"` to disable default footer. | |
|
||||
| flag: `--show-debug-on-error`<br/>toml: `show_debug_on_error` | bool | show detailed error information on error pages (WARNING: this may contain sensitive information - do not use in production) | false |
|
||||
|
||||
### Probe Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ------------------------------------------------------- | ------ | ---------------------------------------------------------- | ----------------------------- |
|
||||
| flag: `--ping-path`<br/>toml: `ping_path` | string | the ping endpoint that can be used for basic health checks | `"/ping"` |
|
||||
| flag: `--ping-user-agent`<br/>toml: `ping_user_agent` | string | a User-Agent that can be used for basic health checks | `""` (don't check user agent) |
|
||||
| flag: `--ready-path`<br/>toml: `ready_path` | string | the ready endpoint that can be used for deep health checks | `"/ready"` |
|
||||
| flag: `--gcp-healthchecks`<br/>toml: `gcp_healthchecks` | bool | Enable GCP/GKE healthcheck endpoints (deprecated) | false |
|
||||
|
||||
### Proxy Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
|
||||
| flag: `--allow-query-semicolons`<br/>toml: `allow_query_semicolons` | bool | allow the use of semicolons in query args ([required for some legacy applications](https://github.com/golang/go/issues/25192)) | `false` |
|
||||
| flag: `--api-route`<br/>toml: `api_routes` | string \| list | return HTTP 401 instead of redirecting to authentication server if token is not valid. Format: path_regex | |
|
||||
| flag: `--authenticated-emails-file`<br/>toml: `authenticated_emails_file` | string | authenticate against emails via file (one per line) | |
|
||||
| flag: `--email-domain`<br/>toml: `email_domains` | string \| list | authenticate emails with the specified domain (may be given multiple times). Use `*` to authenticate any email | |
|
||||
| flag: `--encode-state`<br/>toml: `encode_state` | bool | encode the state parameter as UrlEncodedBase64 | false |
|
||||
| flag: `--extra-jwt-issuers`<br/>toml: `extra_jwt_issuers` | string | if `--skip-jwt-bearer-tokens` is set, a list of extra JWT `issuer=audience` (see a token's `iss`, `aud` fields) pairs (where the issuer URL has a `.well-known/openid-configuration` or a `.well-known/jwks.json`) | |
|
||||
| flag: `--force-https`<br/>toml: `force_https` | bool | enforce https redirect | `false` |
|
||||
| flag: `--force-json-errors`<br/>toml: `force_json_errors` | bool | force JSON errors instead of HTTP error pages or redirects | `false` |
|
||||
| flag: `--htpasswd-file`<br/>toml: `htpasswd_file` | string | additionally authenticate against a htpasswd file. Entries must be created with `htpasswd -B` for bcrypt encryption | |
|
||||
| flag: `--htpasswd-user-group`<br/>toml: `htpasswd_user_groups` | string \| list | the groups to be set on sessions for htpasswd users | |
|
||||
| flag: `--proxy-prefix`<br/>toml: `proxy_prefix` | string | the url root path that this proxy should be nested under (e.g. /`<oauth2>/sign_in`) | `"/oauth2"` |
|
||||
| flag: `--real-client-ip-header`<br/>toml: `real_client_ip_header` | string | Header used to determine the real IP of the client, requires `--reverse-proxy` to be set (one of: X-Forwarded-For, X-Real-IP, or X-ProxyUser-IP) | X-Real-IP |
|
||||
| flag: `--redirect-url`<br/>toml: `redirect_url` | string | the OAuth Redirect URL, e.g. `"https://internalapp.yourcompany.com/oauth2/callback"` | |
|
||||
| flag: `--relative-redirect-url`<br/>toml: `relative_redirect_url` | bool | allow relative OAuth Redirect URL.` | false |
|
||||
| flag: `--reverse-proxy`<br/>toml: `reverse_proxy` | bool | are we running behind a reverse proxy, controls whether headers like X-Real-IP are accepted and allows X-Forwarded-\{Proto,Host,Uri\} headers to be used on redirect selection | false |
|
||||
| flag: `--signature-key`<br/>toml: `signature_key` | string | GAP-Signature request signature key (algorithm:secretkey) | |
|
||||
| flag: `--skip-auth-preflight`<br/>toml: `skip_auth_preflight` | bool | will skip authentication for OPTIONS requests | false |
|
||||
| flag: `--skip-auth-regex`<br/>toml: `skip_auth_regex` | string \| list | (DEPRECATED for `--skip-auth-route`) bypass authentication for requests paths that match (may be given multiple times) | |
|
||||
| flag: `--skip-auth-route`<br/>toml: `skip_auth_routes` | string \| list | bypass authentication for requests that match the method & path. Format: method=path_regex OR method!=path_regex. For all methods: path_regex OR !=path_regex | |
|
||||
| flag: `--skip-jwt-bearer-tokens`<br/>toml: `skip_jwt_bearer_tokens` | bool | will skip requests that have verified JWT bearer tokens (the token must have [`aud`](https://en.wikipedia.org/wiki/JSON_Web_Token#Standard_fields) that matches this client id or one of the extras from `extra-jwt-issuers`) | false |
|
||||
| flag: `--skip-provider-button`<br/>toml: `skip_provider_button` | bool | will skip sign-in-page to directly reach the next step: oauth/start | false |
|
||||
| flag: `--ssl-insecure-skip-verify`<br/>toml: `ssl_insecure_skip_verify` | bool | skip validation of certificates presented when using HTTPS providers | false |
|
||||
| flag: `--trusted-ip`<br/>toml: `trusted_ips` | bool | encode the state parameter as UrlEncodedBase64 | false |
|
||||
| flag: `--whitelist-domain`<br/>toml: `whitelist_domains` | string \| list | allowed domains for redirection after authentication. Prefix domain with a `.` or a `*.` to allow subdomains (e.g. `.example.com`, `*.example.com`) [^2] | |
|
||||
|
||||
[^2]: When using the `whitelist-domain` option, any domain prefixed with a `.` or a `*.` will allow any subdomain of the specified domain as a valid redirect URL. By default, only empty ports are allowed. This translates to allowing the default port of the URL's protocol (80 for HTTP, 443 for HTTPS, etc.) since browsers omit them. To allow only a specific port, add it to the whitelisted domain: `example.com:8080`. To allow any port, use `*`: `example.com:*`.
|
||||
|
||||
### Server Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
|
||||
| flag: `--http-address`<br/>toml: `http_address` | string | `[http://]<addr>:<port>` or `unix://<path>` to listen on for HTTP clients. Square brackets are required for ipv6 address, e.g. `http://[::1]:4180` | `"127.0.0.1:4180"` |
|
||||
| flag: `--https-address`<br/>toml: `https_address` | string | `[https://]<addr>:<port>` to listen on for HTTPS clients. Square brackets are required for ipv6 address, e.g. `https://[::1]:443` | `":443"` |
|
||||
| flag: `--metrics-address`<br/>toml: `metrics_address` | string | the address prometheus metrics will be scraped from | `""` |
|
||||
| flag: `--metrics-secure-address`<br/>toml: `metrics_secure_address` | string | the address prometheus metrics will be scraped from if using HTTPS | `""` |
|
||||
| flag: `--metrics-tls-cert-file`<br/>toml: `metrics_tls_cert_file` | string | path to certificate file for secure metrics server | `""` |
|
||||
| flag: `--metrics-tls-key-file`<br/>toml: `metrics_tls_key_file` | string | path to private key file for secure metrics server | `""` |
|
||||
| flag: `--tls-cert-file`<br/>toml: `tls_cert_file` | string | path to certificate file | |
|
||||
| flag: `--tls-key-file`<br/>toml: `tls_key_file` | string | path to private key file | |
|
||||
| flag: `--tls-cipher-suite`<br/>toml: `tls_cipher_suites` | string \| list | Restricts TLS cipher suites used by server to those listed (e.g. TLS_RSA_WITH_RC4_128_SHA) (may be given multiple times). If not specified, the default Go safe cipher list is used. List of valid cipher suites can be found in the [crypto/tls documentation](https://pkg.go.dev/crypto/tls#pkg-constants). | |
|
||||
| flag: `--tls-min-version`<br/>toml: `tls_min_version` | string | minimum TLS version that is acceptable, either `"TLS1.2"` or `"TLS1.3"` | `"TLS1.2"` |
|
||||
|
||||
### Session Options
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ----------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| flag: `--session-cookie-minimal`<br/>toml: `session_cookie_minimal` | bool | strip OAuth tokens from cookie session stores if they aren't needed (cookie session store only) | false |
|
||||
| flag: `--session-store-type`<br/>toml: `session_store_type` | string | [Session data storage backend](sessions.md); redis or cookie | cookie |
|
||||
| flag: `--redis-cluster-connection-urls`<br/>toml: `redis_cluster_connection_urls` | string \| list | List of Redis cluster connection URLs (e.g. `redis://HOST[:PORT]`). Used in conjunction with `--redis-use-cluster` | |
|
||||
| flag: `--redis-connection-url`<br/>toml: `redis_connection_url` | string | URL of redis server for redis session storage (e.g. `redis://HOST[:PORT]`) | |
|
||||
| flag: `--redis-insecure-skip-tls-verify`<br/>toml: `redis_insecure_skip_tls_verify` | bool | skip TLS verification when connecting to Redis | false |
|
||||
| flag: `--redis-password`<br/>toml: `redis_password` | string | Redis password. Applicable for all Redis configurations. Will override any password set in `--redis-connection-url` | |
|
||||
| flag: `--redis-sentinel-password`<br/>toml: `redis_sentinel_password` | string | Redis sentinel password. Used only for sentinel connection; any redis node passwords need to use `--redis-password` | |
|
||||
| flag: `--redis-sentinel-master-name`<br/>toml: `redis_sentinel_master_name` | string | Redis sentinel master name. Used in conjunction with `--redis-use-sentinel` | |
|
||||
| flag: `--redis-sentinel-connection-urls`<br/>toml: `redis_sentinel_connection_urls` | string \| list | List of Redis sentinel connection URLs (e.g. `redis://HOST[:PORT]`). Used in conjunction with `--redis-use-sentinel` | |
|
||||
| flag: `--redis-use-cluster`<br/>toml: `redis_use_cluster` | bool | Connect to redis cluster. Must set `--redis-cluster-connection-urls` to use this feature | false |
|
||||
| flag: `--redis-use-sentinel`<br/>toml: `redis_use_sentinel` | bool | Connect to redis via sentinels. Must set `--redis-sentinel-master-name` and `--redis-sentinel-connection-urls` to use this feature | false |
|
||||
| flag: `--redis-connection-idle-timeout`<br/>toml: `redis_connection_idle_timeout` | int | Redis connection idle timeout seconds. If Redis [timeout](https://redis.io/docs/reference/clients/#client-timeouts) option is set to non-zero, the `--redis-connection-idle-timeout` must be less than Redis timeout option. Example: if either redis.conf includes `timeout 15` or using `CONFIG SET timeout 15` the `--redis-connection-idle-timeout` must be at least `--redis-connection-idle-timeout=14` | 0 |
|
||||
|
||||
### Upstream Options
|
||||
|
||||
| Flag / Config Field | Type | Description | Default |
|
||||
| ----------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
|
||||
| flag: `--flush-interval`<br/>toml: `flush_interval` | duration | period between flushing response buffers when streaming responses | `"1s"` |
|
||||
| flag: `--pass-host-header`<br/>toml: `pass_host_header` | bool | pass the request Host Header to upstream | true |
|
||||
| flag: `--proxy-websockets`<br/>toml: `proxy_websockets` | bool | enables WebSocket proxying | true |
|
||||
| flag: `--ssl-upstream-insecure-skip-verify`<br/>toml: `ssl_upstream_insecure_skip_verify` | bool | skip validation of certificates presented when using HTTPS upstreams | false |
|
||||
| flag: `--upstream-timeout`<br/>toml: `upstream_timeout` | duration | maximum amount of time the server will wait for a response from the upstream | 30s |
|
||||
| flag: `--upstream`<br/>toml: `upstreams` | string \| list | the http url(s) of the upstream endpoint, file:// paths for static files or `static://<status_code>` for static response. Routing is based on the path | |
|
||||
|
||||
## 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.
|
||||
|
||||
@ -228,7 +269,7 @@ Static file paths are configured as a file:// URL. `file:///var/www/static/` wil
|
||||
|
||||
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](#config-file). When multiple upstreams are used routing to them will be based on the path they are set up with.
|
||||
|
||||
### Environment variables
|
||||
## Environment variables
|
||||
|
||||
Every command line argument can be specified as an environment variable by
|
||||
prefixing it with `OAUTH2_PROXY_`, capitalising it, and replacing hyphens (`-`)
|
||||
@ -253,11 +294,11 @@ Each type of logging has its own configurable format and variables. By default,
|
||||
|
||||
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
|
||||
## 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> - <user@domain.com> [19/Mar/2015:17:20:19 -0400] [<STATUS>] <MESSAGE>
|
||||
<REMOTE_ADDRESS> - <REQUEST ID> - <user@domain.com> [2015/03/19 17:20:19] [<STATUS>] <MESSAGE>
|
||||
```
|
||||
|
||||
The status block will contain one of the below strings:
|
||||
@ -283,16 +324,16 @@ Available variables for auth logging:
|
||||
| Protocol | HTTP/1.0 | The request protocol. |
|
||||
| RequestID | 00010203-0405-4607-8809-0a0b0c0d0e0f | The request ID pulled from the `--request-id-header`. Random UUID if empty |
|
||||
| RequestMethod | GET | The request method. |
|
||||
| Timestamp | 19/Mar/2015:17:20:19 -0400 | The date and time of the logging event. |
|
||||
| Timestamp | 2015/03/19 17:20:19 | The date and time of the logging event. |
|
||||
| UserAgent | - | The full user agent as reported by the requesting client. |
|
||||
| Username | username@email.com | The email or username of the auth request. |
|
||||
| Status | AuthSuccess | The status of the auth request. See above for details. |
|
||||
|
||||
### Request Log Format
|
||||
## Request Log Format
|
||||
HTTP request logs will output by default in the below format:
|
||||
|
||||
```
|
||||
<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>
|
||||
<REMOTE_ADDRESS> - <REQUEST ID> - <user@domain.com> [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.
|
||||
@ -315,16 +356,16 @@ Available variables for request logging:
|
||||
| RequestURI | "/oauth2/auth" | The URI path of the request. |
|
||||
| ResponseSize | 12 | The size in bytes of the response. |
|
||||
| StatusCode | 200 | The HTTP status code of the response. |
|
||||
| Timestamp | 19/Mar/2015:17:20:19 -0400 | The date and time of the logging event. |
|
||||
| Timestamp | 2015/03/19 17:20:19 | The date and time of the logging event. |
|
||||
| Upstream | - | The upstream data of the HTTP request. |
|
||||
| UserAgent | - | The full user agent as reported by the requesting client. |
|
||||
| Username | username@email.com | The email or username of the auth request. |
|
||||
|
||||
### Standard Log Format
|
||||
## 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:
|
||||
|
||||
```
|
||||
[19/Mar/2015:17:20:19 -0400] [main.go:40] <MESSAGE>
|
||||
[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:
|
||||
@ -337,272 +378,6 @@ Available variables for standard logging:
|
||||
|
||||
| Variable | Example | Description |
|
||||
| --------- | --------------------------------- | -------------------------------------------------- |
|
||||
| Timestamp | 19/Mar/2015:17:20:19 -0400 | The date and time of the logging event. |
|
||||
| Timestamp | 2015/03/19 17:20:19 | The date and time of the logging event. |
|
||||
| File | main.go:40 | The file and line number of the logging statement. |
|
||||
| Message | HTTP: listening on 127.0.0.1:4180 | The details of the log statement. |
|
||||
|
||||
## Configuring for use with the Nginx `auth_request` directive
|
||||
|
||||
**This option requires `--reverse-proxy` option to be set.**
|
||||
|
||||
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:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl;
|
||||
server_name ...;
|
||||
include ssl/ssl.conf;
|
||||
|
||||
location /oauth2/ {
|
||||
proxy_pass http://127.0.0.1:4180;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Auth-Request-Redirect $request_uri;
|
||||
# or, if you are handling multiple domains:
|
||||
# proxy_set_header X-Auth-Request-Redirect $scheme://$host$request_uri;
|
||||
}
|
||||
location = /oauth2/auth {
|
||||
proxy_pass http://127.0.0.1:4180;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-Uri $request_uri;
|
||||
# nginx auth_request includes headers but not body
|
||||
proxy_set_header Content-Length "";
|
||||
proxy_pass_request_body off;
|
||||
}
|
||||
|
||||
location / {
|
||||
auth_request /oauth2/auth;
|
||||
error_page 401 =403 /oauth2/sign_in;
|
||||
|
||||
# pass information via X-User and X-Email headers to backend,
|
||||
# requires running with --set-xauthrequest flag
|
||||
auth_request_set $user $upstream_http_x_auth_request_user;
|
||||
auth_request_set $email $upstream_http_x_auth_request_email;
|
||||
proxy_set_header X-User $user;
|
||||
proxy_set_header X-Email $email;
|
||||
|
||||
# if you enabled --pass-access-token, this will pass the token to the backend
|
||||
auth_request_set $token $upstream_http_x_auth_request_access_token;
|
||||
proxy_set_header X-Access-Token $token;
|
||||
|
||||
# if you enabled --cookie-refresh, this is needed for it to work with auth_request
|
||||
auth_request_set $auth_cookie $upstream_http_set_cookie;
|
||||
add_header Set-Cookie $auth_cookie;
|
||||
|
||||
# When using the --set-authorization-header flag, some provider's cookies can exceed the 4kb
|
||||
# limit and so the OAuth2 Proxy splits these into multiple parts.
|
||||
# Nginx normally only copies the first `Set-Cookie` header from the auth_request to the response,
|
||||
# so if your cookies are larger than 4kb, you will need to extract additional cookies manually.
|
||||
auth_request_set $auth_cookie_name_upstream_1 $upstream_cookie_auth_cookie_name_1;
|
||||
|
||||
# Extract the Cookie attributes from the first Set-Cookie header and append them
|
||||
# to the second part ($upstream_cookie_* variables only contain the raw cookie content)
|
||||
if ($auth_cookie ~* "(; .*)") {
|
||||
set $auth_cookie_name_0 $auth_cookie;
|
||||
set $auth_cookie_name_1 "auth_cookie_name_1=$auth_cookie_name_upstream_1$1";
|
||||
}
|
||||
|
||||
# Send both Set-Cookie headers now if there was a second part
|
||||
if ($auth_cookie_name_upstream_1) {
|
||||
add_header Set-Cookie $auth_cookie_name_0;
|
||||
add_header Set-Cookie $auth_cookie_name_1;
|
||||
}
|
||||
|
||||
proxy_pass http://backend/;
|
||||
# or "root /path/to/site;" or "fastcgi_pass ..." etc
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
When you use ingress-nginx in Kubernetes, you MUST use `kubernetes/ingress-nginx` (which includes the Lua module) and the following configuration snippet for your `Ingress`.
|
||||
Variables set with `auth_request_set` are not `set`-able in plain nginx config when the location is processed via `proxy_pass` and then may only be processed by Lua.
|
||||
Note that `nginxinc/kubernetes-ingress` does not include the Lua module.
|
||||
|
||||
```yaml
|
||||
nginx.ingress.kubernetes.io/auth-response-headers: Authorization
|
||||
nginx.ingress.kubernetes.io/auth-signin: https://$host/oauth2/start?rd=$escaped_request_uri
|
||||
nginx.ingress.kubernetes.io/auth-url: https://$host/oauth2/auth
|
||||
nginx.ingress.kubernetes.io/configuration-snippet: |
|
||||
auth_request_set $name_upstream_1 $upstream_cookie_name_1;
|
||||
|
||||
access_by_lua_block {
|
||||
if ngx.var.name_upstream_1 ~= "" then
|
||||
ngx.header["Set-Cookie"] = "name_1=" .. ngx.var.name_upstream_1 .. ngx.var.auth_cookie:match("(; .*)")
|
||||
end
|
||||
}
|
||||
```
|
||||
It is recommended to use `--session-store-type=redis` when expecting large sessions/OIDC tokens (_e.g._ with MS Azure).
|
||||
|
||||
You have to substitute *name* 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=".
|
||||
|
||||
## Configuring for use with the Traefik (v2) `ForwardAuth` middleware
|
||||
|
||||
**This option requires `--reverse-proxy` option to be set.**
|
||||
|
||||
### ForwardAuth with 401 errors middleware
|
||||
|
||||
The [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/forwardauth/) allows Traefik to authenticate requests via the oauth2-proxy's `/oauth2/auth` endpoint on every request, which only returns a 202 Accepted response or a 401 Unauthorized response without proxying the whole request through. For example, on Dynamic File (YAML) Configuration:
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
a-service:
|
||||
rule: "Host(`a-service.example.com`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-errors
|
||||
- oauth-auth
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
oauth:
|
||||
rule: "Host(`a-service.example.com`, `oauth.example.com`) && PathPrefix(`/oauth2/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
|
||||
services:
|
||||
a-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.2:7555
|
||||
oauth-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.1:4180
|
||||
|
||||
middlewares:
|
||||
auth-headers:
|
||||
headers:
|
||||
sslRedirect: true
|
||||
stsSeconds: 315360000
|
||||
browserXssFilter: true
|
||||
contentTypeNosniff: true
|
||||
forceSTSHeader: true
|
||||
sslHost: example.com
|
||||
stsIncludeSubdomains: true
|
||||
stsPreload: true
|
||||
frameDeny: true
|
||||
oauth-auth:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/oauth2/auth
|
||||
trustForwardHeader: true
|
||||
oauth-errors:
|
||||
errors:
|
||||
status:
|
||||
- "401-403"
|
||||
service: oauth-backend
|
||||
query: "/oauth2/sign_in?rd={url}"
|
||||
```
|
||||
|
||||
### ForwardAuth with static upstreams configuration
|
||||
|
||||
Redirect to sign_in functionality provided without the use of `errors` middleware with [Traefik v2 `ForwardAuth` middleware](https://doc.traefik.io/traefik/middlewares/forwardauth/) pointing to oauth2-proxy service's `/` endpoint
|
||||
|
||||
**Following options need to be set on `oauth2-proxy`:**
|
||||
- `--upstream=static://202`: Configures a static response for authenticated sessions
|
||||
- `--reverse-proxy=true`: Enables the use of `X-Forwarded-*` headers to determine redirects correctly
|
||||
|
||||
```yaml
|
||||
http:
|
||||
routers:
|
||||
a-service-route-1:
|
||||
rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-auth-redirect # redirects all unauthenticated to oauth2 signin
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
a-service-route-2:
|
||||
rule: "Host(`a-service.example.com`) && PathPrefix(`/no-auto-redirect`)"
|
||||
service: a-service-backend
|
||||
middlewares:
|
||||
- oauth-auth-wo-redirect # unauthenticated session will return a 401
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
services-oauth2-route:
|
||||
rule: "Host(`a-service.example.com`, `b-service.example.com`) && PathPrefix(`/oauth2/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
oauth2-proxy-route:
|
||||
rule: "Host(`oauth.example.com`) && PathPrefix(`/`)"
|
||||
middlewares:
|
||||
- auth-headers
|
||||
service: oauth-backend
|
||||
tls:
|
||||
certResolver: default
|
||||
domains:
|
||||
- main: "example.com"
|
||||
sans:
|
||||
- "*.example.com"
|
||||
|
||||
services:
|
||||
a-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.2:7555
|
||||
b-service-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.3:7555
|
||||
oauth-backend:
|
||||
loadBalancer:
|
||||
servers:
|
||||
- url: http://172.16.0.1:4180
|
||||
|
||||
middlewares:
|
||||
auth-headers:
|
||||
headers:
|
||||
sslRedirect: true
|
||||
stsSeconds: 315360000
|
||||
browserXssFilter: true
|
||||
contentTypeNosniff: true
|
||||
forceSTSHeader: true
|
||||
sslHost: example.com
|
||||
stsIncludeSubdomains: true
|
||||
stsPreload: true
|
||||
frameDeny: true
|
||||
oauth-auth-redirect:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/
|
||||
trustForwardHeader: true
|
||||
authResponseHeaders:
|
||||
- X-Auth-Request-Access-Token
|
||||
- Authorization
|
||||
oauth-auth-wo-redirect:
|
||||
forwardAuth:
|
||||
address: https://oauth.example.com/oauth2/auth
|
||||
trustForwardHeader: true
|
||||
authResponseHeaders:
|
||||
- X-Auth-Request-Access-Token
|
||||
- Authorization
|
||||
```
|
||||
|
||||
:::note
|
||||
If you set up your OAuth2 provider to rotate your client secret, you can use the `client-secret-file` option to reload the secret when it is updated.
|
||||
:::
|
||||
|
||||
@ -3,6 +3,18 @@ id: github
|
||||
title: GitHub
|
||||
---
|
||||
|
||||
## Config Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ---------------- | -------------- | -------------- | ------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| `--github-org` | `github_org` | string | restrict logins to members of this organisation | |
|
||||
| `--github-team` | `github_team` | string | restrict logins to members of any of these teams (slug), separated by a comma | |
|
||||
| `--github-repo` | `github_repo` | string | restrict logins to collaborators of this repository formatted as `orgname/repo` | |
|
||||
| `--github-token` | `github_token` | string | the token to use when verifying repository collaborators (must have push access to the repository) | |
|
||||
| `--github-user` | `github_users` | string \| list | To allow users to login by username even if they do not belong to the specified org and team or collaborators | |
|
||||
|
||||
## Usage
|
||||
|
||||
1. Create a new project: https://github.com/settings/developers
|
||||
2. Under `Authorization callback URL` enter the correct url ie `https://internal.yourcompany.com/oauth2/callback`
|
||||
|
||||
|
||||
@ -3,6 +3,15 @@ id: gitlab
|
||||
title: GitLab
|
||||
---
|
||||
|
||||
## Config Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ------------------- | ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
|
||||
| `--gitlab-group` | `gitlab_groups` | string \| list | restrict logins to members of any of these groups (slug), separated by a comma | |
|
||||
| `--gitlab-projects` | `gitlab_projects` | string \| list | restrict logins to members of any of these projects (may be given multiple times) formatted as `orgname/repo=accesslevel`. Access level should be a value matching [Gitlab access levels](https://docs.gitlab.com/ee/api/members.html#valid-access-levels), defaulted to 20 if absent | |
|
||||
|
||||
## Usage
|
||||
|
||||
This auth provider has been tested against Gitlab version 12.X. Due to Gitlab API changes, it may not work for version
|
||||
prior to 12.X (see [994](https://github.com/oauth2-proxy/oauth2-proxy/issues/994)).
|
||||
|
||||
|
||||
@ -3,6 +3,18 @@ id: google
|
||||
title: Google (default)
|
||||
---
|
||||
|
||||
## Config Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ---------------------------------------------- | -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
|
||||
| `--google-admin-email` | `google_admin_email` | string | the google admin to impersonate for api calls | |
|
||||
| `--google-group` | `google_groups` | string | restrict logins to members of this google group (may be given multiple times). | |
|
||||
| `--google-service-account-json` | `google_service_account_json` | string | the path to the service account json credentials | |
|
||||
| `--google-use-application-default-credentials` | `google_use_application_default_credentials` | bool | use application default credentials instead of service account json (i.e. GKE Workload Identity) | |
|
||||
| `--google-target-principal` | `google_target_principal` | bool | the target principal to impersonate when using ADC | defaults to the service account configured for ADC |
|
||||
|
||||
## Usage
|
||||
|
||||
For Google, the registration steps are:
|
||||
|
||||
1. Create a new project: https://console.developers.google.com/project
|
||||
@ -31,7 +43,7 @@ account is still authorized.
|
||||
2. Make note of the Client ID for a future step.
|
||||
3. Under "APIs & Auth", choose APIs.
|
||||
4. Click on Admin SDK and then Enable API.
|
||||
5. Follow the steps on https://developers.google.com/workspace/guides/create-credentials#optional_set_up_domain-wide_delegation_for_a_service_account
|
||||
5. Follow the steps on https://developers.google.com/admin-sdk/directory/v1/guides/delegation#delegate_domain-wide_authority_to_your_service_account
|
||||
and give the client id from step 2 the following oauth scopes:
|
||||
|
||||
```
|
||||
|
||||
@ -3,6 +3,14 @@ id: keycloak_oidc
|
||||
title: Keycloak OIDC
|
||||
---
|
||||
|
||||
## Config Options
|
||||
|
||||
| Flag | Toml Field | Type | Description | Default |
|
||||
| ---------------- | --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ | ------- |
|
||||
| `--allowed-role` | `allowed_roles` | string \| list | restrict logins to users with this role (may be given multiple times). Only works with the keycloak-oidc provider. | |
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
--provider=keycloak-oidc
|
||||
--client-id=<your client's id>
|
||||
|
||||
@ -22,6 +22,7 @@
|
||||
"collapsed": false,
|
||||
"items": [
|
||||
"configuration/overview",
|
||||
"configuration/integration",
|
||||
{
|
||||
"type": "category",
|
||||
"label": "OAuth Provider Configuration",
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user