mirror of
https://github.com/fosrl/badger.git
synced 2026-03-26 12:36:49 +00:00
86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
# Pangolin Middleware: Badger
|
|
|
|
Badger is a middleware plugin designed to work with Traefik in conjunction with [Pangolin](https://github.com/fosrl/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](#disabling-forward-auth) section below for details.
|
|
|
|
This plugin is **required** to be installed alongside [Pangolin](https://github.com/fosrl/pangolin) to enforce secure authentication and session management.
|
|
|
|
## Installation
|
|
|
|
Badger is automatically installed with Pangolin. Learn how to install Pangolin in the [Pangolin Documentation](https://docs.pangolin.net/self-host/quick-install).
|
|
|
|
## 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:
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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.
|
|
|
|
```yaml
|
|
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"
|
|
```
|
|
|
|
## Updating Cloudflare IPs
|
|
|
|
To update the Cloudflare IP ranges, run:
|
|
|
|
```bash
|
|
./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](LICENSE) file for details.
|