pangolin_mirror/badger
1
0
Fork 0
mirror of https://github.com/fosrl/badger.git synced 2026-02-23 05:16:47 +00:00
Code Issues Packages Projects Releases Wiki Activity

support pulling real ip from proxy

Browse Source
This commit is contained in:
miloschwartz
2025-12-20 18:30:10 -05:00
parent 52f47fa24e
commit ad3c3b71e6
5 changed files with 307 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
README.md
View File

@@ -1,18 +1,23 @@
# Badger Plugin for Traefik with Pangolin Integration
# Pangolin Middleware: Badger
Badger is a middleware plugin designed to work with the Traefik reverse proxy in conjunction with [Pangolin](https://github.com/fosrl/pangolin), a multi-tenant tunneled reverse proxy server and management interface with identity and access management. Badger acts as an authentication bouncer, ensuring only authenticated and authorized requests are allowed through the proxy.
Badger is a middleware plugin designed to work with the Traefik reverse proxy in conjunction with [Pangolin](https://github.com/fosrl/pangolin), an identity-aware reverse proxy and VPN. Badger acts as an authentication bouncer, ensuring only authenticated and authorized requests are allowed through the proxy.
This plugin is **required** to be configured alongside [Pangolin](https://github.com/fosrl/pangolin) to enforce secure authentication and session management.
> [!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
Learn how to set up [Pangolin](https://github.com/fosrl/pangolin) and Badger in the [Pangolin Documentation](https://github.com/fosrl/pangolin).
Badger is automatically installed with Pangolin. Learn how to install Pangolin in the [Pangolin Documentation](https://docs.pangolin.net/self-host/quick-install).
## Configuration
Badger requires the following configuration parameters to be specified in your [Traefik configuration file](https://doc.traefik.io/traefik/getting-started/configuration-overview/). These coincide with the separate [Pangolin](https://github.com/fosrl/pangolin) configuration file. These options do not need to be configured unless you need to override the automatically provided config from Pangolin.
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.
### Configuration Options
### Required Configuration Options
When forward auth is enabled (default), the following options are required:
```yaml
apiBaseUrl: "http://localhost:3001/api/v1"
@@ -20,6 +25,77 @@ 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:
```yaml
disableForwardAuth: true
# IP handling configuration (optional)
trustip:
- "10.0.0.0/8"
customIPHeader: "X-Forwarded-For"
```
### 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:
```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"
```
### 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:
```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.