SecurityPolicy: JWT Bearer requests rejected by BasicAuth filter when both are configured (no OR semantics)

[QuentinBisson]

Summary

When a SecurityPolicy is configured with both jwt and basicAuth, a request authenticated with a valid JWT Bearer token is rejected by the BasicAuth filter with:

HTTP/2 401
www-authenticate: Basic realm="..."
User authentication failed. Expected 'Basic' authentication scheme.

Similarly, a request authenticated with valid Basic credentials (and jwt.optional not set) gets rejected by the JWT filter with:

HTTP/2 401
www-authenticate: Bearer realm="..."
Jwt is missing

Neither direction works — the two filters apply AND logic in practice, even though users expect OR semantics (accept a request if any one of the configured auth methods succeeds).

Environment

• Envoy Gateway version: v1.6.3
• Kubernetes Gateway API version: v1.2.x

Steps to Reproduce

1. Create a SecurityPolicy with both jwt and basicAuth:

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: SecurityPolicy
metadata:
  name: multi-auth
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: my-route
  jwt:
    providers:
    - name: my-provider
      issuer: "https://issuer.example.com"
      remoteJWKS:
        uri: "https://issuer.example.com/keys"
  basicAuth:
    users:
      name: my-htpasswd-secret

2. Send a request with a valid JWT Bearer token → 401 "Expected 'Basic' authentication scheme"
3. Send a request with valid Basic credentials → 401 "Jwt is missing"

Expected Behavior

A request authenticated via either mechanism should be accepted. If JWT validation succeeds, the BasicAuth filter should not run (or should pass through). Likewise, if the request presents valid Basic credentials and no JWT, the JWT filter should not block it. Requests with no credentials should still be rejected.

Actual Behavior

Both filters always run sequentially. Whichever runs second rejects the request if it does not carry the expected credential type for that filter.

Setting jwt.optional: true fixes the Basic→JWT direction (JWT filter no longer rejects requests without a Bearer token), but the BasicAuth filter has no equivalent optional flag and always rejects requests whose Authorization header is not Basic.

Related

• Discussion Combining OIDC and JWT authentication #2425 describes the same root problem for OIDC+JWT
• Issue Ability to specify authentication mechanism ordering in SecurityPolicies #5367 touches on filter ordering

Workaround

The only currently working workaround is architectural: use separate SecurityPolicies per route, routing JWT-authenticated clients to read routes and BasicAuth-authenticated clients to write routes. This is restrictive and may not suit all use cases.

Proposed Fix

The naive approach of adding optional: true to both jwt and basicAuth is not sufficient: if both filters are individually optional, a request with no credentials at all would pass through both filters unauthenticated.

What is needed is "require at least one" semantics at the SecurityPolicy level. For example, a top-level field:

  requireAnyOne: true   # reject if no auth method succeeded; accept if any one did
  jwt:
    optional: true      # pass through if no Bearer token present
    providers: [...]
  basicAuth:
    optional: true      # pass through if no Basic credentials present
    users:
      name: my-secret

With this model:

• Request with valid JWT Bearer → JWT filter validates, BasicAuth passes through → accepted
• Request with valid Basic credentials → JWT filter passes through, BasicAuth validates → accepted
• Request with no credentials → both filters pass through, requireAnyOne gate rejects → 401
• Request with invalid credentials of either type → the relevant filter rejects → 401

[QuentinBisson]

Root Cause & Fix

After digging into this, the problem is that Envoy's HTTP filter chain is fail-fast and sequential — each filter independently enforces its own auth with no built-in OR semantics.

The specific gaps are:

1. The basic_auth filter has no allow_missing option (unlike the JWT filter which has allow_missing / allow_missing_or_failed), so it always rejects requests whose Authorization header is not Basic.
2. The basic_auth filter emits no dynamic metadata on success, so a downstream RBAC filter has no way to detect that BasicAuth authenticated the request.

Both gaps need to be fixed in Envoy core to unblock this cleanly.

Upstream PR

envoyproxy/envoy#43911 adds both:

• allow_missing: true on the BasicAuth filter: requests with no Basic credentials (missing Authorization header, or a non-Basic scheme like Bearer) pass through instead of being rejected. Requests that do present Basic credentials are still fully validated.
• Dynamic metadata on success: on successful authentication the filter emits envoy.filters.http.basic_auth → {"username": "<authenticated-user>"}, mirroring what the JWT filter already does with JWT claims.

How OR Semantics Work Once the PR Lands

With those two changes, no new Gateway API surface is needed — the existing filters compose:

# JWT filter (already has allow_missing)
jwt:
  providers: [...]
  # allow_missing implicitly handled per-provider

# BasicAuth filter (new allow_missing)
basicAuth:
  users:
    name: my-htpasswd-secret
  allow_missing: true

# RBAC filter — "require at least one auth succeeded"
rbac:
  rules:
    action: ALLOW
    policies:
      require-any-auth:
        permissions: [any: true]
        principals:
        - or_ids:
            ids:
            - metadata:
                filter: envoy.filters.http.jwt_authn
                path: [{key: sub}]
                value: {present_match: true}
            - metadata:
                filter: envoy.filters.http.basic_auth
                path: [{key: username}]
                value: {present_match: true}

Request	JWT filter	BasicAuth filter	RBAC	Result
Valid Bearer token	validates → sets metadata	passes through (no Basic)	JWT metadata present	✅ 200
Valid Basic credentials	passes through (no Bearer)	validates → sets metadata	basic_auth metadata present	✅ 200
No credentials	passes through	passes through	no metadata → deny	❌ 403
Invalid credentials	rejects (if Bearer) or BasicAuth rejects	rejects (if Basic)	—	❌ 401

Once the Envoy PR is merged and the new allow_missing field is available in go-control-plane, Envoy Gateway can wire it up automatically when both jwt and basicAuth are present in a SecurityPolicy.

[arkodg]

cc @zhaohuabing

[zhaohuabing]

@QuentinBisson This approach looks solid, and thanks for adding the missing piece to the Envoy basic auth filter.

One additional point: we may still need to explicitly model the “or” logic in the Envoy Gateway API, since allow_missing only applies to a single auth method and does not require another one must exist.

The API below is just for discussion. While it would have broader impact, it could also be useful for other authentication methods, such as API key auth, ext auth, and OIDC.

spec:
  authentication:
    mode: Any   # default: All
  jwt:
    providers:
    - name: my-provider
      ...
  basicAuth:
    users:
      name: my-secret

[QuentinBisson]

@zhaohuabing Thank you, once the other PR is merged I will see if I can implement this but I quite like your approach if I'm being honest