OAuth2 Proxy

https://oauth2-proxy.github.io/oauth2-proxy/
Admin
A reverse proxy and static file server that provides authentication using Providers (Google, GitHub,...
Tokens:52,722
Snippets:398
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Launch Dex server

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/openid_connect

Command to start Dex from the $GOPATH/github.com/dexidp/dex directory.

```bash
bin/dex serve examples/config-dev.yaml  
```

--------------------------------

### Start oauth2-proxy with login.gov provider

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/login_gov

Start oauth2-proxy with the login.gov provider. Requires a registered application with the specified issuer, redirect URI, and a PEM public key. The example uses the login.gov integration sandbox URLs and assumes local proxy and upstream addresses.

```bash
./oauth2-proxy -provider login.gov \
  -client-id=${LOGINGOV_ISSUER} \
  -redirect-url=http://localhost:4180/oauth2/callback \
  -oidc-issuer-url=https://idp.int.identitysandbox.gov/ \
  -cookie-secure=false \
  -email-domain=gsa.gov \
  -upstream=http://localhost:3000/ \
  -cookie-secret=somerandomstring12341234567890AB \
  -cookie-domain=localhost \
  -skip-provider-button=true \
  -pubjwk-url=https://idp.int.identitysandbox.gov/api/openid_connect/certs \
  -profile-url=https://idp.int.identitysandbox.gov/api/openid_connect/userinfo \
  -jwt-key="${OAUTH2_PROXY_JWT_KEY}"
```

--------------------------------

### Install latest release with go install

Source: https://oauth2-proxy.github.io/oauth2-proxy/installation

Installs the latest release of OAuth2 Proxy into $GOPATH/bin. Ensure $GOPATH is in your $PATH so the binary is found.

```bash
$ go install github.com/oauth2-proxy/oauth2-proxy/v7@latest  
```

--------------------------------

### Download Dex with go get

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/openid_connect

Command to download the Dex OpenID Connect provider.

```bash
go get github.com/dexidp/dex  
```

--------------------------------

### Start OAuth2 Proxy with alpha config

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/alpha-config

Starts OAuth2 Proxy using the new alpha configuration file while still referencing the existing config. Use after converting and removing unsupported options.

```bash
oauth2-proxy --alpha-config ./path/to/new/config.yaml --config ./path/to/existing/config.cfg  
```

--------------------------------

### Example config file /etc/localhost.cfg

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/openid_connect

Configuration file for oauth2-proxy using Okta as the OIDC provider. It sets the provider to 'oidc', specifies the Okta issuer URL, and includes settings for localhost testing such as cookie_secure=false and skip_provider_button=true. The client_id and client_secret are placeholders to be replaced with actual values from the Okta application.

```ini
provider = "oidc"  

redirect_url = "http://localhost:4180/oauth2/callback"  

oidc_issuer_url = "https://${your-okta-domain}/oauth2/default"  

upstreams = [  

    "http://0.0.0.0:8080"  

]  

email_domains = [  

    "*"  

]  

client_id = "XXX"  

client_secret = "YYY"  

pass_access_token = true  

cookie_secret = "ZZZ"  

cookie_secure = false  

skip_provider_button = true  

# Note: use the following for testing within a container  

# http_address = "0.0.0.0:4180"  

```

--------------------------------

### Okta oauth2-proxy configuration file

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/openid_connect

Configuration file example for using Okta as the OIDC provider, including provider, redirect URL, issuer URL, upstreams, email domains, client credentials, and cookie settings.

```ini
provider = "oidc"  
redirect_url = "https://example.corp.com/oauth2/callback"  
oidc_issuer_url = "https://corp.okta.com/oauth2/abCd1234"  
upstreams = [  
    "https://example.corp.com"  
]  
email_domains = [  
    "corp.com"  
]  
client_id = "XXXXX"  
client_secret = "YYYYY"  
pass_access_token = true  
cookie_secret = "ZZZZZ"  
skip_provider_button = true  
```

--------------------------------

### Keycloak OIDC provider usage example

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/keycloak_oidc

Command-line configuration for the keycloak-oidc provider. Includes client credentials, redirect URL, issuer URL, email domain validation, optional role and group restrictions, and PKCE. Note the issuer URL format for Keycloak versions before 17.

```bash
    --provider=keycloak-oidc  

    --client-id=<your client's id>  

    --client-secret=<your client's secret>  

    --redirect-url=https://internal.yourcompany.com/oauth2/callback  

    --oidc-issuer-url=https://<keycloak host>/realms/<your realm> // For Keycloak versions <17: --oidc-issuer-url=https://<keycloak host>/auth/realms/<your realm>  

    --email-domain=<yourcompany.com> // Validate email domain for users, see option documentation  

    --allowed-role=<realm role name> // Optional, required realm role  

    --allowed-role=<client id>:<client role name> // Optional, required client role  

    --allowed-group=</group name> // Optional, requires group client scope  

    --code-challenge-method=S256 // PKCE  

```

--------------------------------

### Migrating header injections in v7.14.0

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/alpha-config

Migration example showing the required nesting of header injection sources from v7.14.0 onward. The 'before' block uses squashed fields (claim, value) while the 'after' block nests them under claimSource and secretSource.

```yaml
# before v7.14.0  
injectRequestHeaders:  
- name: X-Forwarded-User  
  values:  
  - claim: user  
- name: X-Custom-Secret-header  
  values:  
  - value: my-super-secret  

# v7.14.0 and later  
injectRequestHeaders:  
- name: X-Forwarded-User  
  values:  
  - claimSource:  
      claim: user  
- name: X-Custom-Secret-header  
  values:  
  - secretSource:  
      value: my-super-secret  

```

--------------------------------

### Verify prebuilt binary checksum with sha256sum

Source: https://oauth2-proxy.github.io/oauth2-proxy/installation

Validates a prebuilt binary against the sha256sum.txt checksum file provided for each release starting with v3.0.0. The output shows a successful verification.

```bash
$ sha256sum -c sha256sum.txt  
oauth2-proxy-x.y.z.linux-amd64: OK  
```

--------------------------------

### Validate configuration with --config-test

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview

Validates the configuration file without starting the proxy server. The first command tests a legacy config, the second tests an alpha config, and the third is a CI/CD pre-deployment check. Returns exit code 1 if any validation errors occur.

```bash
# Test legacy config  
oauth2-proxy --config /etc/oauth2-proxy.cfg --config-test  
  
# Test alpha config  
oauth2-proxy --config /etc/core.cfg --alpha-config /etc/alpha.yaml --config-test  
  
# CI/CD pre-deployment check  
# Returns with exit code 1 if any validation errors occur  
oauth2-proxy --config new-config.cfg --config-test   
```

--------------------------------

### Federated credential Terraform example

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/ms_entra_id

Terraform example for creating a federated identity credential for workload identity authentication. Requires a cluster with a public OIDC issuer URL and the Workload Identity admission webhook deployed.

```hcl
    resource "azuread_application_federated_identity_credential" "fedcred" {  

        application_id = azuread_application.application.id # ID of your application  

        display_name   = "federation-cred"  

        description    = "Workload identity for oauth2-proxy"  

        audiences      = ["api://AzureADTokenExchange"] # Fixed value  

        issuer         = "https://cluster-oidc-issuer-url..."  

        subject        = "system:serviceaccount:oauth2-proxy-namespace-name:oauth2-proxy-sa-name" # set proper NS and SA name  

    }  

```

--------------------------------

### Browser-facing route with redirect

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/integrations/nginx

For browser-facing routes, redirect authentication failures to the sign-in page. This ensures users get a smooth login flow.

```nginx
location / {
  auth_request /oauth2/auth;
  error_page 401 = @oauth2_signin;
  proxy_pass http://backend/;
}

location @oauth2_signin {
  return 302 /oauth2/sign_in?rd=$scheme://$host$request_uri;
}

```

--------------------------------

### Cidaas hierarchical groups and roles claim

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/cidaas

Example of hierarchical groups and roles claims returned by Cidaas. The provider transforms this structure into a flat list of groups.

```json
{
  "groups": [
    {
      "groupId": "group1",
      "roles": ["role1", "role2"]
    },
    {
      "groupId": "group2",
      "roles": ["role3"]
    }
  ]
}
```

--------------------------------

### Run oauth2-proxy with OIDC provider arguments

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/openid_connect

Command-line arguments to run oauth2-proxy with the OIDC provider, including client credentials, issuer URL, and cookie settings.

```bash
--provider oidc  
--provider-display-name "My OIDC Provider"  
--client-id oauth2-proxy  
--client-secret proxy  
--redirect-url http://127.0.0.1:4180/oauth2/callback  
--oidc-issuer-url http://127.0.0.1:5556/dex  
--cookie-secure=false  
--cookie-secret=secret  
--email-domain kilgore.trout  
```

--------------------------------

### Validate alpha config with --config-test

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/alpha-config

Validates the alpha configuration without starting the proxy. Useful for CI/CD pipelines to catch configuration errors before deployment.

```bash
oauth2-proxy --config core.cfg --alpha-config alpha.yaml --config-test  
```

--------------------------------

### Serve current directory as static endpoint

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/openid_connect

Additional argument to serve the current working directory as a website under the /static endpoint.

```bash
--upstream file://$PWD/#/static/  
```

--------------------------------

### GET /oauth2/auth

Source: https://oauth2-proxy.github.io/oauth2-proxy/features/endpoints

This endpoint returns a 202 Accepted response or a 401 Unauthorized response. It is intended for use with the Nginx `auth_request` directive. It can be configured using the following query parameters: `allowed_groups`, `allowed_email_domains`, and `allowed_emails`.

```APIDOC
## GET /oauth2/auth

### Description
This endpoint returns a 202 Accepted response or a 401 Unauthorized response. It is intended for use with the Nginx `auth_request` directive. It can be configured using the following query parameters: `allowed_groups`, `allowed_email_domains`, and `allowed_emails`.

### Method
GET

### Endpoint
/oauth2/auth

### Parameters
#### Query Parameters
- **allowed_groups** (string) - Optional - Comma separated list of allowed groups.
- **allowed_email_domains** (string) - Optional - Comma separated list of allowed email domains.
- **allowed_emails** (string) - Optional - Comma separated list of allowed emails.

### Request Example
GET /oauth2/auth?allowed_groups=group1,group2

### Response
#### Success Response (202)
- No response body is documented.

#### Error Response (401)
- No response body is documented.

#### Response Example
No response body is documented.
```

--------------------------------

### Nextcloud provider command-line configuration

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/nextcloud

Command-line arguments to configure the Nextcloud provider. Requires the client ID and secret from the Nextcloud admin, and the login, redeem, and validate URLs. The validate URL must not include 'index.php'.

```bash
-provider nextcloud  

-client-id <from nextcloud admin>  

-client-secret <from nextcloud admin>  

-login-url="<your nextcloud url>/index.php/apps/oauth2/authorize"  

-redeem-url="<your nextcloud url>/index.php/apps/oauth2/api/v1/token"  

-validate-url="<your nextcloud url>/ocs/v2.php/cloud/user?format=json"  

```

--------------------------------

### Run oauth2-proxy with --http-address=fd:3

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/systemd_socket

Command to run oauth2-proxy with systemd socket activation. The --http-address=fd:3 parameter tells oauth2-proxy to use the file descriptor passed by systemd (the first non-stdin/stdout/stderr). Replace the placeholder values with your actual configuration.

```bash
./oauth2-proxy \  

    --http-address="fd:3" \  

    --email-domain="yourcompany.com"  \  

    --upstream=http://127.0.0.1:8080/ \  

    --cookie-secret=... \  

    --cookie-secure=true \  

    --provider=... \  

    --client-id=... \  

    --client-secret=...  

```

--------------------------------

### Standard Logging Format Defaults

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/overview

These are the default formats for the standard logging output. The first shows the literal default output, and the second shows the template used when configuring the --standard-logging-format flag.

```text

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

```

```

```text

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

```

```

--------------------------------

### Convert existing config to alpha format

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/alpha-config

Converts an existing configuration file to the new alpha YAML format and prints the result to STDOUT. Use before adding the --alpha-config option.

```bash
oauth2-proxy --convert-config-to-alpha --config ./path/to/existing/config.cfg  
```

--------------------------------

### GET /

Source: https://oauth2-proxy.github.io/oauth2-proxy/features/endpoints

This endpoint returns the upstream response if authenticated. If unauthenticated it returns a 401 Unauthorized. If the authenticated user is not in one of the allowed groups, or emails then it returns a 403 forbidden. It can be configured using the following query parameters: `allowed_groups`, `allowed_email_domains`, and `allowed_emails`.

```APIDOC
## GET /

### Description
This endpoint returns the upstream response if authenticated. If unauthenticated it returns a 401 Unauthorized. If the authenticated user is not in one of the allowed groups, or emails then it returns a 403 forbidden. It can be configured using the following query parameters: `allowed_groups`, `allowed_email_domains`, and `allowed_emails`.

### Method
GET

### Endpoint
/

### Parameters
#### Query Parameters
- **allowed_groups** (string) - Optional - Comma separated list of allowed groups.
- **allowed_email_domains** (string) - Optional - Comma separated list of allowed email domains.
- **allowed_emails** (string) - Optional - Comma separated list of allowed emails.

### Request Example
GET /?allowed_groups=group1,group2

### Response
#### Success Response (200)
- Returns the upstream response.

#### Error Response (401)
- No response body is documented.

#### Error Response (403)
- No response body is documented.

#### Response Example
No response body is documented.
```

--------------------------------

### Run oauth2-proxy with TLS termination at OAuth2 Proxy

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/tls

Run oauth2-proxy with TLS termination at the proxy itself. Requires --tls-cert-file and --tls-key-file. The minimal TLS version defaults to TLS1.2 and can be set with --tls-min-version; TLS1.3 is always the maximal version. Cipher suites can be set with --tls-cipher-suite, otherwise defaults from crypto/tls are used.

```bash
./oauth2-proxy \  

    --email-domain="yourcompany.com"  \  

    --upstream=http://127.0.0.1:8080/ \  

    --tls-cert-file=/path/to/cert.pem \  

    --tls-key-file=/path/to/cert.key \  

    --cookie-secret=... \  

    --cookie-secure=true \  

    --provider=... \  

    --client-id=... \  

    --client-secret=...  


```

--------------------------------

### GET /oauth2/sign_out

Source: https://oauth2-proxy.github.io/oauth2-proxy/features/endpoints

This endpoint clears the session cookie and can be used to sign the user out. It only removes oauth2-proxy's own cookies, so the user may still be logged in with the authentication provider. To redirect the user to the provider's sign-out page, use the `rd` query parameter or the `X-Auth-Request-Redirect` header.

```APIDOC
## GET /oauth2/sign_out

### Description
This endpoint clears the session cookie and can be used to sign the user out. It only removes oauth2-proxy's own cookies, so the user may still be logged in with the authentication provider. To redirect the user to the provider's sign-out page, use the `rd` query parameter or the `X-Auth-Request-Redirect` header.

### Method
GET

### Endpoint
/oauth2/sign_out

### Parameters
#### Query Parameters
- **rd** (string) - Optional - The URL to redirect the user to after sign-out. Must be URL-encoded and the domain must be in the `--whitelist-domain` configuration. Supports the `{id_token}` placeholder.

#### Headers
- **X-Auth-Request-Redirect** (string) - Optional - The URL to redirect the user to after sign-out. Must be URL-encoded and the domain must be in the `--whitelist-domain` configuration. Supports the `{id_token}` placeholder.

### Request Example
GET /oauth2/sign_out?rd=https%3A%2F%2Fmy-oidc-provider.example.com%2Fsign_out_page

### Response
#### Success Response (200)
- No response body is documented.

#### Response Example
No response body is documented.
```

--------------------------------

### Single-tenant app with up to 200 groups

Source: https://oauth2-proxy.github.io/oauth2-proxy/configuration/providers/ms_entra_id

Configuration for a single-tenant app with up to 200 groups (groups claim enabled). Consider using the generic OIDC provider instead.

```text
provider="entra-id"  
oidc_issuer_url="https://login.microsoftonline.com/<tenant-id>/v2.0"  
client_id="<client-id>"  
client_secret="<client-secret>"  
scope="openid"  
allowed_groups=["ac51800c-2679-4ecb-8130-636380a3b491"]  

```
Tokens:
Raw