vouch-proxy

packaged by Chainguard

Chainguard Container for vouch-proxy

Vouch Proxy is an SSO and OAuth / OIDC login solution for Nginx using the auth_request module.

Chainguard Containers are regularly-updated, secure-by-default container images.

Download this Container Image

For those with access, this container image is available on cgr.dev:

docker pull cgr.dev/ORGANIZATION/vouch-proxy:latest

Be sure to replace the ORGANIZATION placeholder with the name used for your organization's private repository within the Chainguard Registry.

Compatibility Notes

The vouch-proxy image is comparable to the upstream Vouch Proxy image (quay.io/vouch/vouch-proxy) and is designed to be a drop-in replacement for it. It keeps the upstream /vouch-proxy entrypoint, the / working directory, port 9090, and the /config/config.yml configuration path. It also runs as the non-root vouch user (UID/GID 999), as upstream does.

The image differs from upstream in the following ways:

• The Vouch Proxy binary is installed at /usr/bin/vouch-proxy, and /vouch-proxy is a compatibility symlink to it. The image sets VOUCH_ROOT=/ so that Vouch Proxy still resolves its configuration from /config/config.yml.
• The image is built on Chainguard OS and contains only Vouch Proxy and its runtime dependencies. It does not include a shell or package manager, which reduces the attack surface.

Getting Started

Vouch Proxy is written in Go and licensed under the MIT License. It is intended to be paired with an Nginx (or Ingress) auth_request directive: Nginx forwards each request to Vouch Proxy's /validate endpoint, and Vouch Proxy answers 200 for a valid session cookie or 401 to trigger the OAuth / OIDC login flow.

Vouch Proxy reads its configuration from config/config.yml relative to its root directory, which this image sets to /. Mount your own configuration at /config/config.yml and publish port 9090:

docker run -d --rm --name vouch-proxy -p 9090:9090 \
  -v "$(pwd)/config:/config" \
  cgr.dev/ORGANIZATION/vouch-proxy:latest

A minimal config/config.yml looks like this:

vouch:
  listen: 0.0.0.0
  port: 9090
  domains:
    - example.com
  jwt:
    secret: a-secret-of-at-least-forty-four-characters-long
oauth:
  provider: google
  client_id: your-client-id
  client_secret: your-client-secret
  callback_url: https://vouch.example.com:9090/auth

Once the container is running, GET /validate without a session cookie returns 401, and GET /login?url=... redirects to your identity provider's authorization endpoint. The /healthcheck endpoint reports readiness:

curl -fsS http://localhost:9090/healthcheck

{ "ok": true }

The binary's built-in -healthcheck flag probes an already-running Vouch Proxy over that same endpoint, so run it inside the daemon container rather than starting a new one:

docker exec vouch-proxy /vouch-proxy -healthcheck

Configuration

Every configuration key can also be supplied as an environment variable, for example VOUCH_PORT, VOUCH_DOMAINS, VOUCH_JWT_SECRET, OAUTH_PROVIDER, OAUTH_CLIENT_ID, and OAUTH_CLIENT_SECRET. Set VOUCH_CONFIG to load a configuration file from an alternate path.

The image exposes port 9090/tcp, the Vouch Proxy HTTP listener that serves the /validate, /login, /auth, /logout, and /healthcheck endpoints.

The container runs as the non-root vouch user (UID/GID 999). Any mounted configuration directory must be readable by that user, and writable if you let Vouch Proxy generate its own JWT secret.

Documentation and Resources

• Vouch Proxy on GitHub
• Vouch Proxy example configuration
• Nginx auth_request module documentation
• Chainguard Academy

What are Chainguard Containers?

Chainguard's free tier of Starter container images are built with Wolfi, our minimal Linux undistro.

All other Chainguard Containers are built with Chainguard OS, Chainguard's minimal Linux operating system designed to produce container images that meet the requirements of a more secure software supply chain.

The main features of Chainguard Containers include:

• Minimal design, without unnecessary software bloat
• Daily builds to ensure container images are up-to-date with available security patches
• High quality build-time SBOMs attesting to the provenance of all artifacts within the image
• Verifiable signatures provided by Sigstore
• Reproducible builds with Cosign and apko (read more about reproducibility)

For cases where you need container images with shells and package managers to build or debug, most Chainguard Containers come paired with a development, or -dev, variant.

In all other cases, including Chainguard Containers tagged as :latest or with a specific version number, the container images include only an open-source application and its runtime dependencies. These minimal container images typically do not contain a shell or package manager.

Although the -dev container image variants have similar security features as their more minimal versions, they include additional software that is typically not necessary in production environments. We recommend using multi-stage builds to copy artifacts from the -dev variant into a more minimal production image.

Need additional packages?

To improve security, Chainguard Containers include only essential dependencies. Need more packages? Chainguard customers can use Custom Assembly to add packages, either through the Console, chainctl, or API.

To use Custom Assembly in the Chainguard Console: navigate to the image you'd like to customize in your Organization's list of images, and click on the Customize image button at the top of the page.

Learn More

Refer to our Chainguard Containers documentation on Chainguard Academy. Chainguard also offers VMs and Libraries — contact us for access.

Trademarks

This software listing is packaged by Chainguard. The trademarks set forth in this offering are owned by their respective companies, and use of them does not imply any affiliation, sponsorship, or endorsement by such companies.