Hwi Oauth Proxy Bundle Laravel Package

Getting Started

1. Install alongside HWIOAuthBundle. The proxy bundle is an add-on, not a replacement — you still need hwi/oauth-bundle and at least one resource owner configured.

   composer require hwi/oauth-bundle guilhermednt/hwi-oauth-proxy-bundle
   

2. Register the bundle. Append the bundle class from the README to config/bundles.php (confirm the exact FQCN by listing vendor/guilhermednt/hwi-oauth-proxy-bundle/src/). In legacy Symfony, add it to AppKernel::registerBundles().
3. Look at two files first: DependencyInjection/Configuration.php (the actual config tree — it is the source of truth for keys, defaults, and required fields) and Resources/config/services.yaml (the service IDs and which HWIOAuthBundle service is decorated). bin/console debug:config hwi_oauth_proxy and debug:container --tag=hwi_oauth.* are the fastest way to see what is wired.
4. Pick your first use case. There are two distinct "proxy" problems this package targets, and you should confirm which one your version implements:
   • Egress proxy: outbound token/userinfo calls from HWIOAuthBundle go through a corporate HTTP(S) proxy.
   • Ingress proxy: the app sits behind a TLS-terminating load balancer or tunnel, and the OAuth redirect_uri must be built from the public scheme/host rather than the backend request.
5. Smoke test with one provider. Configure a single resource owner (e.g. GitHub), hit /_oauth/login/github, and watch the redirect_uri query parameter on the provider's authorize URL. That one value tells you whether the proxy layer is working.

Implementation Patterns

Environment-scoped proxy configuration. Keep proxy settings per-environment so local/dev can use a tunnel (ngrok, localtunnel) while prod uses a real egress proxy:

# config/packages/hwi_oauth_proxy.yaml
hwi_oauth_proxy:
    # exact keys depend on the bundle's Configuration.php
    proxy: '%env(resolve:OAUTH_PROXY_URL)%'   # e.g. http://user:[email protected]:3128
    no_proxy: ['localhost', '127.0.0.1', '.internal']

# .env.local
OAUTH_PROXY_URL=http://127.0.0.1:8888   # mitmproxy/Charles for debugging

Correct callback URLs behind a load balancer. This is the pattern most teams actually need. Combine the bundle with Symfony's own trusted-proxy support so Request::getSchemeAndHttpHost() returns the public URL:

# config/packages/framework.yaml
framework:
    trusted_proxies: '%env(TRUSTED_PROXIES)%'
    trusted_headers: ['x-forwarded-for', 'x-forwarded-proto', 'x-forwarded-host', 'x-forwarded-port']
    router:
        default_uri: 'https://app.example.com'

Then keep the OAuth callback route on a stable, public host — many providers (Google, Facebook) reject redirect_uri values that don't match registered ones exactly, including scheme and port.

Firewall wiring stays standard HWIOAuthBundle. The proxy layer sits underneath, so your security.yaml is unchanged:

security:
    firewalls:
        main:
            oauth:
                resource_owners:
                    github: '/login/check-github'
                login_path: /login
                use_forward: false
                failure_path: /login

Testing pattern. Inject a MockHttpClient / a fake proxy and assert that the authorize redirect carries the expected redirect_uri. Functional tests that boot the kernel with TRUSTED_PROXIES=127.0.0.1 and a spoofed X-Forwarded-Proto: https header catch the majority of regressions before deploy.

Extension point. If the bundle's built-in config doesn't cover your case, decorate the HWIOAuthBundle HTTP client service in your own services.yaml instead of forking. That keeps the upgrade path clean, which matters for a package with this little downstream usage.

Gotchas and Tips

• The redirect_uri mismatch is the #1 failure mode. If the provider says "redirect_uri_mismatch," dump $request->getSchemeAndHttpHost() inside the controller that builds the authorize URL. If it says http:// while you registered https://, it's a trusted-proxies problem, not an OAuth problem.
• Two proxies, one app. If the app is behind a reverse proxy and makes outbound calls through an egress proxy, configure both independently. Setting one usually does not fix the other, and symptoms look identical from the provider's side.
• Credentials in env, never in YAML. Proxy URLs commonly contain user:pass@. Use %env(resolve:...)% and make sure the env var is excluded from config dumps (bin/console debug:config will print it).
• no_proxy matters more than you think. Internal token-validation endpoints, metadata servers, and health checks should bypass the proxy or your OAuth flow will hang on a request that was never meant to leave the network.
• Trusted-proxy scope. trusted_proxies should be the load balancer's CIDR, not 0.0.0.0/0. Overly broad trust lets any client spoof X-Forwarded-Host and poison the callback URL — a real vulnerability in OAuth flows.
• Session cookie domain. When proxying across subdomains (e.g. auth.example.com → app.example.com), the state/oauth_state session cookie must be scoped correctly or the callback lands on an empty session and HWIOAuthBundle reports an invalid state.
• Debugging the wire. Enable Guzzle debug output or Symfony's HTTP client profiler; for a tunnel/proxy setup, point at mitmproxy first and confirm the exact Host and redirect_uri being sent. Most "proxy bugs" are visible in one request.
• Version pinning. With ~1 star and 0 dependents, expect no security advisories and no compatibility guarantees. Pin the package ("guilhermednt/hwi-oauth-proxy-bundle": "x.y.*"), read the source before upgrading HWIOAuthBundle across majors, and be prepared to vendor or replace it with a small service decorator if it stalls. The decorator approach is roughly 30 lines and removes the dependency entirely.
• Check compatibility early. HWIOAuthBundle changed its HTTP client abstraction across versions; verify which HttpClientInterface the bundle decorates by running bin/console debug:container --show-arguments <decorated_service_id> before you spend time debugging config that targets the wrong service.