envoyproxy / envoyproxy/gateway

[Feature Request] `claimToHeaders` support for OIDC in SecurityPolicy

Open
#9,380 2 comments 0 reactions 0 assignees View on GitHub
stale triage
Dominant language
Go
Stars
3k
Forks
864
Avg merge
2d 2h
Merged PRs (30d)
140

Description

Request to add `claimToHeaders` in `spec.oidc` in the `SecurityPolicy`

**Component**: SecurityPolicy / OIDC
**Envoy Gateway version:** v1.8.1
**CRD**: v1.8.1

**Current behaviour**
`claimToHeaders` is available under `spec.jwt.providers[*].claimToHeaders` in `SecurityPolicy`, allowing JWT claims to be extracted and injected as HTTP request headers to upstream services.

The equivalent field does **not exist** under `spec.oidc` in the `SecurityPolicy` CRD. The full set of available OIDC fields is:

`clientID`, `clientIDRef`, `clientSecret`, `cookieConfig`, `cookieDomain`, `cookieNames`, `csrfTokenTTL`, `defaultRefreshTokenTTL`, `defaultTokenTTL`, `denyRedirect`, `disableTokenEncryption`, `forwardAccessToken`, `forwardIDToken`, `logoutPath`, `passThroughAuthHeader`, `provider`, `redirectURL`, `refreshToken`, `resources`, `scopes

**Expected behaviour**

`spec.oidc.claimToHeaders` should be available with the same schema as the JWT equivalent, allowing claims from the validated OIDC ID token to be injected as named HTTP request headers:

```yaml
spec:
oidc:
provider:
issuer: https://login.microsoftonline.com//v2.0
clientID:
clientSecret:
name: my-secret
namespace: my-namespace
redirectURL: https://example.com/oauth2/callback
scopes: [openid, email, profile]
claimToHeaders:
- claim: email
header: X-User
- claim: preferred_username
header: X-Auth-Request-Preferred-Username
- claim: groups
header: X-Auth-Request-Groups
```

**Motivation**

When migrating from nginx ingress with oauth2-proxy (`auth_request` + `auth_request_set` + `proxy_set_header`) to Envoy Gateway native OIDC, the nginx configuration pattern of extracting claims and renaming them as upstream request headers has no equivalent. Specifically:

```nginx
auth_request_set $user $upstream_http_x_auth_request_email;
proxy_set_header X-User $user;
```

Backend services rely on specific named headers (e.g. `X-User`) derived from OIDC claims. Without `claimToHeaders` on OIDC, the options are:

- Change backend services to accept different header names — undesirable, may affect multiple services
- Use `forwardIDToken` and have backends decode the JWT themselves — requires backend changes and adds JWT parsing overhead
- Use oauth2-proxy as ExtAuth — reintroduces the component OIDC SecurityPolicy was intended to replace, and `headersToBackend` cannot rename headers
- Use JWT SecurityPolicy alongside OIDC to re-validate the forwarded token and inject claims — complex, untested combination, doubles token validation

**JWT `claimToHeaders` schema for reference** (already present in the CRD):

```json
{
"items": {
"properties": {
"claim": { "type": "string" },
"header": { "type": "string" }
},
"required": ["claim", "header"],
"type": "object"
},
"type": "array"
}
```

The OIDC implementation already validates the ID token and has access to its claims internally; surfacing them as configurable headers would be a natural extension of the existing JWT capability.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by comparing the existing JWT claimToHeaders schema and behavior with the OIDC SecurityPolicy CRD and implementation. Trace how validated OIDC ID-token claims are handled, then add equivalent configuration support and verify that configured claims become the named upstream headers described in the request.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, kubernetes
Domain
api, authentication
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.