Proxy Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require fideloper/proxy
   

2. Publish the config (optional but recommended for customization):

   php artisan vendor:publish --provider="Fideloper\Proxy\TrustProxiesServiceProvider" --tag="config"
   

3. Add middleware to app/Http/Kernel.php:

   protected $middleware = [
       // ...
       \Fideloper\Proxy\TrustProxies::class,
   ];
   

4. Configure trusted proxies in config/trustproxies.php:

   'proxies' => '192.168.1.1, 127.0.0.1', // Comma-separated list of trusted proxy IPs
   

First Use Case

Fix HTTPS detection behind a proxy: If your app redirects HTTP → HTTPS but fails due to proxy headers, enable:

'trusted_proxies' => '*', // Trust all proxies (use cautiously)
'headers' => TrustProxies::HEADER_X_FORWARDED_ALL, // Trust X-Forwarded-* headers

Implementation Patterns

Core Workflows

1. Trusting Proxies:

   • Single IP: proxies => '192.168.1.1'
   • Network CIDR: proxies => '192.168.1.0/24'
   • All Proxies: proxies => '*' (use only in trusted environments like staging).

2. Header Configuration:

   • Trust all X-Forwarded-* headers:

     'headers' => TrustProxies::HEADER_X_FORWARDED_ALL
     

   • Trust only specific headers (e.g., IP and host):

     'headers' => TrustProxies::HEADER_X_FORWARDED_FOR | TrustProxies::HEADER_X_FORWARDED_HOST
     

3. Dynamic Trust:

   • Use TrustProxies::check() in middleware to conditionally trust proxies:

     if (TrustProxies::check($request)) {
         // Proceed with trusted logic
     }
     

Integration Tips

• Laravel URL Generation: The package ensures url(), secure_url(), and asset() generate correct URLs behind proxies. Example:

  $url = url('/dashboard'); // Now respects X-Forwarded-Host
  

• Rate Limiting: Use TrustProxies::ip() to get the real client IP for accurate rate limiting:

  RateLimiter::for('api')->by($request->ip()); // Fallback to TrustProxies::ip()
  

• Logging: Log the real client IP using:

  \Log::info('Client IP', ['ip' => TrustProxies::ip($request)]);
  

• Middleware Stacking: Place TrustProxies before other middleware that relies on accurate request data (e.g., VerifyCsrfToken).

Gotchas and Tips

Pitfalls

1. Over-Trusting Proxies:

   • proxies => '*' exposes your app to header spoofing. Restrict to known IPs in production.
   • Fix: Use CIDR notation for internal networks:

     'proxies' => '10.0.0.0/8, 172.16.0.0/12'
     

2. Mixed Content Redirects:

   • If secure_url() generates HTTP links behind HTTPS proxies, ensure:

     'trusted_proxies' => env('TRUSTED_PROXIES', '127.0.0.1, ::1'),
     'headers' => TrustProxies::HEADER_X_FORWARDED_ALL,
     'scheme' => 'https', // Force HTTPS if behind a proxy
     

3. Local Development Issues:

   • On localhost, use:

     'proxies' => '127.0.0.1, ::1'
     

   • Avoid * in local environments to prevent header spoofing.

4. Cloudflare/ELB Headers:

   • Cloudflare adds CF-Connecting-IP. To trust it, extend the package:

     TrustProxies::setHeader('CF-Connecting-IP', 'X-Forwarded-For');
     

Debugging

• Verify Trusted IPs:

  if (!TrustProxies::check($request)) {
      \Log::warning('Request not from a trusted proxy', ['ip' => $request->ip()]);
  }
  

• Inspect Headers: Dump forwarded headers to debug:

  \Log::debug('Forwarded Headers', [
      'X-Forwarded-For' => $request->header('X-Forwarded-For'),
      'X-Forwarded-Host' => $request->header('X-Forwarded-Host'),
  ]);
  

Extension Points

1. Custom Headers: Extend the package to trust additional headers (e.g., X-Real-IP):

   TrustProxies::setHeader('X-Real-IP', 'X-Forwarded-For');
   

2. Dynamic Proxy Lists: Load trusted proxies from an external source (e.g., API):

   $trustedProxies = config('services.trusted_proxies_api');
   TrustProxies::setTrustedProxies($trustedProxies);
   

3. Middleware Logic: Override the default middleware behavior:

   public function handle($request, Closure $next) {
       if (app()->environment('production')) {
           TrustProxies::setTrustedProxies(['192.168.1.1']);
       }
       return $next($request);
   }
   

4. Testing: Mock proxies in tests:

   TrustProxies::setTrustedProxies(['127.0.0.1']);
   $request = new Request([], [], [], [], [], ['HTTP_X_FORWARDED_FOR' => '192.168.1.100']);