Summary
A header confusion vulnerability in Caddy's forward_auth feature allows remote clients to inject or override identity-related headers that PHP/FastCGI applications treat as trusted.
By exploiting differences in how Caddy and PHP/FastCGI normalize header names, an attacker can bypass the intended header cleanup and impersonate users or manipulate group membership when certain identity headers are used.
Affected context
This weakness appears in deployments where Caddy sits in front of PHP/FastCGI applications and uses forward_auth with copy_headers to propagate identity or group headers from an authentication gateway.
It becomes relevant when downstream PHP/FastCGI applications rely on specific HTTP headers (e.g., X-User, X-Group) as trusted identity sources and do not independently verify or normalize these headers.
The risk is most pronounced in environments where identity headers are used to establish session context, impersonation, or role-based access decisions.
Exploit preconditions
- Attack surface: HTTP requests sent to a Caddy instance configured with
forward_authand proxying to PHP/FastCGI backends. - Required access: Ability to send crafted requests to the Caddy server (no special privileges beyond network access).
- Trigger point: The request passes through
forward_auth copy_headers, which removes specific header names but not their underscore aliases, and is then handled byphp_fastcgi, which normalizes header names by converting-to_. - Why exploitation is possible: Caddy deletes the exact header names it distrusts but leaves underscore variants intact, while PHP/FastCGI later treats headers with
-and_as equivalent CGI variables, enabling injection or overriding of identity-related values.
Why this happens
The root cause is a mismatch in header name handling between Caddy and PHP/FastCGI, combined with reliance on headers for identity.
Caddy's forward_auth copy_headers performs header deletion based on literal names (such as X-User) and does not account for equivalent underscore-based variants (such as X_User).
When the request reaches php_fastcgi, Caddy normalizes HTTP headers into CGI environment variables by replacing - with _, causing headers like X-User and X_User to converge into the same backend variable.
This pattern aligns with CWE-287 (Improper Authentication) and CWE-290 (Authentication Bypass by Spoofing), because the system trusts identity information delivered via HTTP headers without robust normalization and verification.
Potential impact
- Remote clients may impersonate other users by injecting identity headers that PHP/FastCGI backends trust.
- Attackers can potentially override group or role headers, leading to unauthorized access to privileged functionality.
- PHP/FastCGI applications can be tricked into making authorization decisions based on forged identity metadata.
- Multi-tenant or shared hosting environments may see cross-tenant data exposure if header-based identity isolation is used.
General mitigation guidance
Effective mitigation focuses on reducing trust in raw HTTP headers for identity and ensuring consistent normalization across components.
Common defensive patterns include:
- Treating identity and authorization information as part of a secure token or session mechanism rather than plain headers.
- Implementing strict header normalization rules at the edge, ensuring that alias forms (e.g.,
X-UserandX_User) are treated uniformly for allow/deny decisions. - Limiting which headers can be set or overridden by clients and reserving certain identity-related header names exclusively for trusted upstreams.
- Performing server-side checks in backend applications to validate that identity information comes from secure sources (e.g., signed tokens, server-generated headers).
- Using least-privilege design for headers, where downstream applications avoid mapping trusted headers directly to high-risk authorization decisions without additional verification.
How teams detect issues like this
Detection often involves a mix of configuration review and code-level analysis:
- Reviewing Caddy configurations for
forward_authandcopy_headersusage, looking for identity or group-related headers that are trusted by downstream PHP/FastCGI applications. - Performing static or configuration analysis on backend PHP/FastCGI code to identify logic that relies on HTTP headers or CGI environment variables for authentication or authorization.
- Applying policy-based checks in CI/CD pipelines that flag identity-related headers and require explicit justification or secure handling patterns.
- Using automated security scanners or rule-based tools configured to detect header normalization inconsistencies and trust of client-supplied headers.

