badger/README.md

Pangolin Middleware: Badger

Badger is a middleware plugin designed to work with Traefik in conjunction with Pangolin, an identity-aware reverse proxy and zero-trust VPN. Badger acts as an authentication bouncer, ensuring only authenticated and authorized requests are allowed through the proxy.

Note

Badger can also be used standalone for IP handling (Cloudflare and custom proxy support) without Pangolin. Simply set disableForwardAuth: true in your configuration. See the Disabling Forward Auth section below for details.

This plugin is required to be installed alongside Pangolin to enforce secure authentication and session management.

Installation

Badger is automatically installed with Pangolin. Learn how to install Pangolin in the Pangolin Documentation.

Configuration

Pangolin will provide the necessary configuration to Badger automatically via the HTTP provider. However, you can override the configuration settings by manually providing them in the Traefik config.

Required Configuration Options

When forward auth is enabled (default), the following options are required:

apiBaseUrl: "http://localhost:3001/api/v1"
userSessionCookieName: "p_session_token"
resourceSessionRequestParam: "p_session_request"

Disabling Forward Auth

To disable forward auth and only use IP handling, set disableForwardAuth: true. When enabled, all requests pass through without authentication, and the required configuration options above are not needed:

Only do this if you do not need Pangolin's authentication features and only want IP handling.

disableForwardAuth: true

IP Handling Configuration

Badger automatically extracts the real client IP from requests. By default, it trusts Cloudflare IP ranges and uses the CF-Connecting-IP header.

Using with Cloudflare (Default)

No additional configuration needed. Badger automatically:

• Trusts Cloudflare IP ranges
• Extracts IP from CF-Connecting-IP header
• Sets X-Real-IP and X-Forwarded-For headers for downstream services

Using without Cloudflare

If you're using a different proxy or load balancer, configure custom trusted IPs and/or a custom IP header:

Ensure you always disable the default Cloudflare IP ranges by setting disableDefaultCFIPs: true and provide your own trusted IP ranges in CIDR format under trustip if using a different proxy.

apiBaseUrl: "http://localhost:3001/api/v1"
userSessionCookieName: "p_session_token"
resourceSessionRequestParam: "p_session_request"

# Disable Cloudflare IP ranges
disableDefaultCFIPs: true

# Add your proxy/load balancer IP ranges (CIDR format)
trustip:
  - "10.0.0.0/8"
  - "172.16.0.0/12"

# Optional: Use a custom header instead of CF-Connecting-IP
customIPHeader: "X-Forwarded-For"

Configuration Options Reference

Option	Type	Required*	Default	Description
disableForwardAuth	bool	No	false	Disable forward auth; only IP handling is performed
apiBaseUrl	string	Yes*	-	Base URL of the Pangolin API
userSessionCookieName	string	Yes*	-	Cookie name for user sessions
resourceSessionRequestParam	string	Yes*	-	Query parameter name for resource session requests
trustip	[]string	No	[]	Array of trusted IP ranges in CIDR format
disableDefaultCFIPs	bool	No	false	Disable default Cloudflare IP ranges
customIPHeader	string	No	""	Custom header name to extract IP from (only used if request is from trusted source)

* Required only when disableForwardAuth is false (default)

Updating Cloudflare IPs

To update the Cloudflare IP ranges, run:

./updateCFIps.sh

This fetches the latest IP ranges from Cloudflare and updates ips/ips.go.

License

This project is licensed under the MIT License - see the LICENSE file for details.