Ipwhitelistshaper
Middleware for Traefiks dynamic configuration and IpAllowList for dynamic IP whitelisting
Install / Use
/learn @hhftechnology/IpwhitelistshaperREADME
📝 Forums
See the forums for further discussion here
How It Works
This Traefik plugin provides a dynamic IP whitelisting mechanism with an admin approval flow. When a user tries to access a protected service and is not in the whitelist, they can request temporary access through a special endpoint. An administrator receives a notification with an approval link that can whitelist the user's IP for a configurable amount of time.
The flow works as follows:
- User tries to access a protected service → gets 403 Forbidden response
- User visits the knock-knock endpoint (e.g.,
/knock-knock) to request access - Admin receives a notification with the user's IP, a random validation code, and an approval link
- Admin verifies the user (using the validation code) and clicks the approval link
- User's IP is whitelisted for a limited time period
- After the time period expires, the IP is automatically removed from the whitelist
Features
- Dynamic IP Whitelisting: Temporarily whitelist IP addresses with automatic expiration
- Admin Approval Flow: Secure approval process with validation codes
- File-Based State Storage: Maintains state across multiple Traefik instances using persistent storage
- Multiple Notification Options: Support for Discord webhooks and other notification services
- Smart Client IP Detection: Support for X-Forwarded-For headers and configurable depth for proxy environments
- Secure Token Generation: HMAC-based token generation for approval links
- Configurable Expiration: Set how long approved IPs remain in the whitelist
- Permanent Whitelisting: Permanently whitelist specific IPs or networks
- Pretty UI: Clean HTML interface for users requesting access and admins approving requests
Configuration
Static Configuration
Enable the plugin in your Traefik static configuration:
# Static configuration
experimental:
plugins:
ipwhitelistshaper:
moduleName: github.com/hhftechnology/ipwhitelistshaper
version: v1.0.3
Dynamic Configuration
Configure the middleware in your dynamic configuration:
# Dynamic configuration
http:
middlewares:
my-ipwhitelistshaper:
plugin:
ipwhitelistshaper:
# Base URL for approval links
approvalURL: "https://your-traefik-instance.example.com"
# URL for notifications (e.g., Discord webhook)
notificationURL: "https://discord.com/api/webhooks/your-webhook-id"
# Default endpoint for requesting access
knockEndpoint: "/knock-knock"
# Allow private networks by default (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
defaultPrivateClassSources: true
# Configure how long (in seconds) an approved IP should remain in the whitelist
expirationTime: 300
# Depth to look into X-Forwarded-For header (set to 1 if behind CloudFlare or another proxy)
ipStrategyDepth: 0
# IPs to exclude from X-Forwarded-For processing
excludedIPs: []
# Permanently whitelisted IPs (in addition to defaults)
whitelistedIPs: []
# Secret key for secure token generation (auto-generated if not provided)
secretKey: ""
# File-based storage configuration
storageEnabled: true
storagePath: "/plugins-storage/ipwhitelistshaper"
saveInterval: 30 # Save every 30 seconds
File-Based Storage
This plugin now includes a file-based storage system to maintain state across Traefik instances and restarts. This ensures that approval tokens and whitelisted IPs remain valid even when Traefik instances are restarted or when requests are handled by different instances.
How File Storage Works
-
Persistent State: The plugin periodically saves its state to disk, including:
- Currently whitelisted IPs and their expiration times
- Pending approval requests and their tokens
- Last request times for rate limiting
-
Automatic Recovery: When the plugin starts, it automatically loads the previously saved state from disk
-
Concurrent Safety: The storage system is designed to be thread-safe and handles concurrent access properly
Storage Configuration
You can configure the storage system with these parameters:
storageEnabled: Enable or disable file-based storage (default: true)storagePath: Directory where state files will be stored (default: "/plugins-storage/ipwhitelistshaper")saveInterval: How often to save state to disk in seconds (default: 30)
Volume Mounting
To use file-based storage with Docker, you need to mount a volume to the storage path:
volumes:
- ./traefik/plugins-storage:/plugins-storage:rw
This ensures that the storage directory is persistent and accessible to Traefik.
Example Router Configuration
Apply the middleware to your HTTP routers to protect your services:
http:
routers:
# Main router that applies the whitelist protection
protected-service:
rule: "Host(`service.example.com`)"
service: "my-service"
middlewares:
- "my-ipwhitelistshaper"
# Special router to handle the knock-knock endpoint
knock-knock-router:
rule: "Host(`service.example.com`) && Path(`/knock-knock`)"
service: "my-service"
middlewares:
- "my-ipwhitelistshaper"
priority: 110 # Higher priority than the main router
# Special router to handle the approval endpoint
approve-router:
rule: "Host(`service.example.com`) && PathPrefix(`/approve/`)"
service: "my-service"
middlewares:
- "my-ipwhitelistshaper"
priority: 110 # Higher priority than the main router
Important: You must define separate routers for the knock-knock and approve endpoints with higher priority than your main router. This ensures that these special paths are correctly handled by the middleware.
Notifications
The plugin sends two types of notifications:
- Access Request Notifications: When a user visits the knock-knock endpoint, a notification is sent with their IP, a validation code, and an approval link.
- Status Notifications: When an IP is approved or expires.
Discord Webhook Integration
To use Discord for notifications:
- Create a webhook in your Discord server (Server Settings → Integrations → Webhooks)
- Copy the webhook URL
- Add it to your configuration:
ipwhitelistshaper:
notificationURL: "https://discord.com/api/webhooks/your-webhook-id/your-webhook-token"
The plugin automatically detects Discord webhook URLs and formats messages appropriately.
Other Notification Services
For other webhook-based notification services, simply provide the webhook URL:
ipwhitelistshaper:
notificationURL: "https://your-notification-service.example.com/webhook"
Messages are sent with a message parameter in the request body.
Usage Behind a Proxy (like CloudFlare)
If your Traefik instance runs behind another proxy (like CloudFlare), you'll need to adjust the IP strategy to correctly identify client IPs:
ipwhitelistshaper:
# Use depth 1 to get the client IP from X-Forwarded-For when behind one proxy
ipStrategyDepth: 1
Or alternatively, use the excludedIPs strategy:
ipwhitelistshaper:
# Exclude CloudFlare IPs from X-Forwarded-For processing
excludedIPs:
- "103.21.244.0/22"
- "103.22.200.0/22"
# Add more CloudFlare IP ranges
For Middleware-manager
- id: "ipwhitelistshaper"
name: "IP Whitelist Shaper"
type: "plugin"
config:
ipwhitelistshaper:
knockEndpoint: "/knock-knock"
approvalURL: "https://wallos.development.hhf.technology"
notificationURL: "https://discord.com/api/webhooks/"
defaultPrivateClassSources: true
expirationTime: 300
ipStrategyDepth: 0
secretKey: ""
excludedIPs: []
whitelistedIPs:
Related Skills
node-connect
354.0kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
frontend-design
112.2kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
openai-whisper-api
354.0kTranscribe audio via OpenAI Audio Transcriptions API (Whisper).
qqbot-media
354.0kQQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。
