Skip to main content

Vouch Proxy

What is Vouch Proxy?​

Vouch Proxy is an OIDC/OAuth2 single sign-on proxy for Nginx using the auth_request module. It validates every request before reaching your applications and handles authentication through your chosen identity provider. Vouch Proxy and Authelia are mutually exclusive; you can only have one installed.

Supported Identity Providers​

Vouch Proxy supports many identity providers including:

  • Okta
  • Google
  • GitHub (and GitHub Enterprise)
  • Azure AD
  • Keycloak
  • Gitea
  • Nextcloud
  • Any generic OIDC provider (Ping Identity, Auth0, etc.)

How It Works​

  1. User visits your protected application
  2. Nginx forwards the request to Vouch Proxy's /validate endpoint
  3. If valid JWT cookie exists → request passes through (HTTP 200)
  4. If no valid cookie → redirect to IdP login (HTTP 401)
  5. User logs in at their IdP
  6. Vouch Proxy receives authorization and sets a JWT cookie
  7. Cookie is valid across all protected subdomains

Prerequisites​

Before installing Vouch Proxy, you need to:

  1. Register an OAuth2/OIDC application with your chosen identity provider
  2. Obtain these credentials:
    • Client ID
    • Client Secret
    • Authorization URL (auth endpoint)
    • Token URL
    • User Info URL
  3. Set the callback URL to: https://YOUR_DOMAIN/vouch/auth

Finding IdP Endpoints​

Most OIDC providers publish their endpoints at:

https://YOUR_IDP/.well-known/openid-configuration

For example, Okta publishes theirs at:

https://myorg.okta.com/.well-known/openid-configuration

Installation​

Basic Installation​

box install vouchproxy \
  --auth-url URL \
  --token-url URL \
  --userinfo-url URL \
  --client-id ID \
  --client-secret SECRET \
  --domain example.com

Installation with Okta (Example)​

box install vouchproxy \
  --auth-url https://myorg.okta.com/oauth2/v1/authorize \
  --token-url https://myorg.okta.com/oauth2/v1/token \
  --userinfo-url https://myorg.okta.com/oauth2/v1/userinfo \
  --client-id 0oa1234567abcdefgh \
  --client-secret your_client_secret \
  --domain example.com

Optional Flags​

  • --end-session-endpoint URL - IdP logout/revocation endpoint for logout support
  • --email-domains CSV - Restrict logins to specific email domains (comma-separated)
  • --oidc-user USER - OIDC username allowed to access local admin (default: local admin username)
  • --oidc-map CSV - Map OIDC usernames to local admin (comma-separated)

Management​

  • Update: box update vouchproxy
  • Remove: box remove vouchproxy

Authentication Migration​

If you're migrating from another auth provider:

qbAuthMigrate --provider vouch

This command handles provider-aware Nginx auth migration and preserves existing configurations.

Limitation

qbAuthMigrate can only migrate from basic or store authentication to basic authentication. It cannot directly convert existing Authelia or Vouch Proxy configurations.

Requirements​

  • Docker must be installed
  • Valid HTTPS domain for Vouch Proxy
  • OAuth2/OIDC credentials from your identity provider
  • Network access to your IdP's endpoints