OAuth2-Proxy Header Injection#

Header injection is how oauth2-proxy propagates authenticated session claims — user identity, email, groups, tokens, and custom OIDC claims — into HTTP request and response headers before forwarding them to upstream services. It is central to patterns like NGINX auth_request, where the upstream reads X-Auth-Request-User, X-Auth-Request-Email, and X-Auth-Request-Groups to authorize the caller.

Architecture#

Injection is a two-layer pipeline:

options.Header config
       │
       ▼
header.NewInjector() ← pkg/header/injector.go
       │
       ├─ newSecretInjector() (static value from env/file/literal)
       └─ newClaimInjector() (dynamic value from SessionState)
               │
               ▼
    SessionState.GetClaim() ← pkg/apis/sessions/session_state.go
               │
               ▼
middleware.NewRequestHeaderInjector() / NewResponseHeaderInjector()
               │ │
         req.Header rw.Header()

pkg/header/injector.go — The core abstraction. NewInjector accepts a []options.Header config slice and builds a flat list of valueInjector closures — one per (header name, value source) pair. At request time, Inject(header, session) iterates every closure and calls header.Add().

Each HeaderValue holds exactly one source — either a SecretSource (static literal, env var, or file) or a ClaimSource (session claim). Supplying both is an error 1.

pkg/apis/options/header.go — Defines the config structs:

• Header: holds the header name, a preserveRequestValue toggle, an InsecureSkipHeaderNormalization toggle, and a []HeaderValue slice.
• ClaimSource: specifies the claim name (see available claims), an optional prefix, and an optional basicAuthPassword for Authorization: Basic encoding.

pkg/middleware/headers.go — Wraps the injector as Alice middleware. NewRequestHeaderInjector additionally prepends a stripping pass that removes any incoming header matching the configured name (normalized) before injecting — preventing clients from spoofing injected headers. Response injection via NewResponseHeaderInjector writes to rw.Header() instead. After injection, flattenHeaders collapses multi-value headers into a single comma-joined string for all headers except Set-Cookie.

Available Claims#

SessionState.GetClaim maps claim names to SessionState fields and returns []string:

Groups are inherently multi-valued. GetClaim("groups") returns the full []string slice, and newClaimInjector calls header.Add(name, claim) for each element 2. This means X-Auth-Request-Groups will appear as multiple header instances — unless flattenHeaders collapses them to a comma-separated value 3.

Default Headers: --set-xauthrequest#

The legacy flag --set-xauthrequest 4 enables a fixed set of response headers. Internally, it calls getXAuthRequestHeaders(), which constructs four options.Header entries:

All four are added to InjectResponseHeaders 5. The flag description in code still says "X-Auth-Request-User and X-Auth-Request-Email" 6 but the actual implementation also adds groups and preferred username — a documentation lag from when groups support was added.

Custom Header Configuration (Alpha API)#

Beyond the legacy flag, headers are fully configurable via the alpha YAML API under injectRequestHeaders and injectResponseHeaders 7. Example patterns:

• Forwarding the ID token as a Bearer token: ClaimSource{Claim: "id_token", Prefix: "Bearer "} (see injector_test.go)
• Basic auth from user claim: ClaimSource{Claim: "user", BasicAuthPassword: &SecretSource{...}} — encodes user:password as Authorization: Basic <base64> 8
• Static headers from env/file: SecretSource{FromEnv: "MY_VAR"} 9
• Multi-value same header: list multiple Values entries under one header name; each becomes an additional header.Add() call 10

Header Normalization and Stripping#

By default, header names are Title-Cased and underscores converted to dashes, following common HTTP practice 11. Set InsecureSkipHeaderNormalization: true per header to disable this. Normalization also governs what incoming headers get stripped: stripNormalizedHeader compares normalized forms to remove case/underscore variants of the configured name before injecting. To preserve an incoming header value instead of stripping it, set preserveRequestValue: true 12.

Key Files#