oauth2: add allow_failed_matcher for unauthenticated pass-through on auth failure by mchen391 · Pull Request #43027 · envoyproxy/envoy

mchen391 · 2026-01-16T01:41:52Z

Commit Message:

This PR adds an allow_failed_matcher field to the OAuth2 filter configuration, enabling requests to proceed to upstream as unauthenticated when OAuth validation fails (missing, invalid, or expired credentials) and the request matches the configured matchers.

This enables graceful degradation patterns where services can handle both authenticated and unauthenticated requests, similar to the JWT filter's allow_missing_or_failed functionality.

When triggered:

All OAuth cookies are stripped from the request
Context headers x-envoy-oauth-status: failed and x-envoy-oauth-failure-reason are added
Request continues to upstream as unauthenticated

Matcher evaluation order: pass_through_matcher > allow_failed_matcher > deny_redirect_matcher > default behavior.

Signed-off-by: Mo Chen carterchen.m@gmail.com

Additional Description:

Use case: An API that returns personalized results for authenticated requests but falls back to generic results for unauthenticated requests.

Example configuration:

allow_failed_matcher:
  - name: ":path"
    string_match:
      prefix: "/api/public"

Risk Level: Medium

Testing:
Added unit tests covering multiple scenarios (no cookies, invalid refresh token, async/sync failures, OAuth callback path, matcher precedence). All existing OAuth2 tests pass. Verified backward compatibility.

Docs Changes: Updated proto documentation for allow_failed_matcher field. Added release notes to changelogs/current.yaml.

Release Notes: Added to changelogs/current.yaml

Platform Specific Features: N/A

[Optional Runtime guard:] N/A - Config-guarded feature (optional proto field)
[Optional Fixes #Issue] Fixes #36523
[Optional API Considerations:]

New optional field allow_failed_matcher (field 27) to OAuth2Config proto
Backward compatible - no behavior change when not configured
Uses existing HeaderMatcher type, follows same pattern as other matchers in OAuth2Config

…auth failure This PR adds an allow_failed_matcher field to the OAuth2 filter configuration, enabling requests to proceed to upstream as unauthenticated when OAuth validation fails (missing, invalid, or expired credentials) and the request matches the configured matchers. This feature enables graceful degradation patterns where services can handle both authenticated and unauthenticated requests, similar to the JWT filter's allow_missing_or_failed functionality. Implementation details: - Added allow_failed_matcher field to OAuth2Config proto (field 27) - The matcher is evaluated in the request flow after pass_through_matcher (which skips validation entirely) and before deny_redirect_matcher - OAuth validation is always attempted (unlike pass_through_matcher which skips it) - When OAuth validation fails AND the request matches allow_failed_matcher, all OAuth cookies are stripped from the request before forwarding to upstream - Context headers added: x-envoy-oauth-status: failed and x-envoy-oauth-failure-reason - Added new statistic oauth_allow_failed_passthrough to track when this path is taken - Updated filter logic in filter.cc and oauth_client.cc to handle the new matcher - Added comprehensive unit tests in filter_test.cc and oauth_test.cc The implementation follows the same architectural pattern as other matchers in the OAuth2 filter and maintains backward compatibility (optional field with no behavior change when not configured). Signed-off-by: Mo Chen <carterchen.m@gmail.com>

repokitteh-read-only · 2026-01-16T01:41:58Z

Hi @mchen391, welcome and thank you for your contribution.

We will try to review your Pull Request as quickly as possible.

In the meantime, please take a look at the contribution guidelines if you have not done so already.

🐱

Caused by: #43027 was opened by mchen391.

see: more, trace.

repokitteh-read-only · 2026-01-16T01:42:04Z

CC @envoyproxy/api-shepherds: Your approval is needed for changes made to (api/envoy/|docs/root/api-docs/).
envoyproxy/api-shepherds assignee is @markdroth
CC @envoyproxy/api-watchers: FYI only for changes made to (api/envoy/|docs/root/api-docs/).

🐱

Caused by: #43027 was opened by mchen391.

see: more, trace.

mchen391 · 2026-01-16T17:39:55Z

source/extensions/filters/http/oauth2/oauth_client.cc

+    return absl::OkStatus();
  } else {
-    parent_->sendUnauthorizedResponse("Token endpoint cluster not found");
+    return absl::UnavailableError("Token endpoint cluster not found");


Although this error is thrown inside oauth_client, it is not an error thrown from the async context and as a result it cannot call parent_->asyncOnUnauthorized. To allow this sync failure and forward the request to upstream, it needs to go back to filter.cc and let it return FilterHeadersStatus::Continue.

tyxia · 2026-01-16T18:13:13Z

Hi @zhaohuabing, I saw you contributed a lot to this area in the past. Could we borrow your expertise to review this PR

cc @wbpcode as code owner as well

Thanks!

zhaohuabing · 2026-01-19T12:35:21Z

Use case: An API that returns personalized results for authenticated requests but falls back to generic results for unauthenticated requests.

Can't this be achieved with Custom Response?

Here is an example using Envoy Gateway BackendTrafficPolicy.

mchen391 · 2026-01-19T16:30:34Z

@zhaohuabing Unless the local reply is able to forward the request to upstream, no unfortunately. Imagine the homepage of a website - it will render normally for anonymous users, but will render tailored content for logged-in users too. Or imagine a search engine API that gives anonymous users result (likely from DB) but also gives tailored result to users with credentials. As a result, we need the request that does not carry any oauth credentials to still forward to upstream and let upstream handles the request.

zhaohuabing · 2026-01-27T10:55:06Z

I think we could redirect unauthenticated requests. Since the OAuth2 filter is already fairly complex, it might be better to handle this in a more generalized way rather than adding another knob to the OAuth2 filter.

https://github.com/zhaohuabing/playground/blob/main/gateway/oidc-keycloak/response-override-redirect.yaml

mchen391 · 2026-01-27T18:21:59Z

I think we could redirect unauthenticated requests. Since the OAuth2 filter is already fairly complex, it might be better to handle this in a more generalized way rather than adding another knob to the OAuth2 filter.

https://github.com/zhaohuabing/playground/blob/main/gateway/oidc-keycloak/response-override-redirect.yaml

@zhaohuabing Sorry I still don't think this would solve the problem. In this case we do NOT want to show the anonymous user an error page, but instead want to show them a normal content but just not tailored for them since they are anonymous.

Just imagine the google homepage - you will be able to load google and use its search engine without login completely fine, but can also do that in a logged-in state, with maybe some tailored search result sorting if you search in logged-in state.

I don't see a clean way to achieve that with redirects. One thing I can think of is to make a duplicate set of all the APIs that are supposed to be optional auth (could work with or without auth), one require auth and one does not require, and make the former redirect to the latter if auth failed. You could imagine that there are going to tons of endpoints that need to be duplicated and maintained separately, which I don't think is ideal or maintenable.

In fact I think the Envoy jwt_authn filter's allow_missing_or_failed option is also designed with this requirement in mind. https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/http/jwt_authn/v3/config.proto#envoy-v3-api-field-extensions-filters-http-jwt-authn-v3-jwtrequirement-allow-missing-or-failed

zhaohuabing · 2026-01-28T02:20:53Z

Thanks for the clarification — I don’t think you necessarily need a full duplicate setup, but it's true that you’d still need some separate routing or handling logic for unauthenticated vs authenticated requests, which would require changes on the application side and isn’t ideal. In that case, having a pass-through option is really helpful. So this approach seems reasonable to me.

markdroth · 2026-01-28T02:23:49Z

/lgtm api

zhaohuabing · 2026-01-28T02:26:10Z

api/envoy/extensions/filters/http/oauth2/v3/oauth.proto

+  //
+  // Note: If a request matches pass_through_matcher, it bypasses OAuth validation and this matcher won't be evaluated.
+  // This matcher takes precedence over deny_redirect_matcher.
+  repeated config.route.v3.HeaderMatcher allow_failed_matcher = 27;


Should this matcher take precedence over deny_redirect_matcher?

deny_redirect_matcher won't redirect matching requests to the oauth server, which happens before auth fails/succeeds.

Correct me if I'm wrong, but I think the filter works in this way:

First of all, if pass_through_matcher matches, skip the entire filter

Do auth on OAuth cookies, refresh token if needed. If auth succeeded, forward to upstream

If auth failed (could be missing cookies, refresh failure, etc), it will either
a. redirect to OAuth server to start a new OAuth, or
b. If deny_redirect_matcher matches, do not redirect and reject with a 401.

As a result, deny_redirect_matcher check happens after auth, and is determining what is the behavior when auth failed. I think this new allow_failed_matcher is in fact defining a new behavior after a & b:

c. If allow_failed_matcher matches, allow this auth failure and forward to upstream

So it's in fact in parallel to deny_redirect_matcher. Technically it's ok for either of them to take precedes over the other one, but I feel like c happens before b makes more sense. Please let me know if you think other way though!

source/extensions/filters/http/oauth2/filter.cc

zhaohuabing · 2026-01-28T02:38:33Z

source/extensions/filters/http/oauth2/filter.cc

+}
+
+void OAuth2Filter::continueAsUnauthorized(const std::string& failure_reason) {
+  removeOAuthTokenCookies(*request_headers_);


unauthenticated requests shouldn’t have those cookies?

Unauthenticated requests could be:

A request without any oauth cookies

A request with expired oauth cookies, especially an expired refresh token, which cannot be used to obtain a new access token any more

The clean up of the token cookies are for the 2nd case.

zhaohuabing · 2026-01-28T02:44:34Z

source/extensions/filters/http/oauth2/filter.cc

 bool OAuth2Filter::canRedirectToOAuthServer(Http::RequestHeaderMap& headers) const {
+  for (const auto& matcher : config_->allowFailedMatchers()) {
+    if (matcher->matchesHeaders(headers)) {
+      ENVOY_LOG(debug, "allow_failed_matcher matched, will not redirect");


request matching allowFailedMatchers should be directed to the OAuth2 server to start the oauth flow.

I actually intentionally let requests matching allowFailedMatchers to never initiate a new OAuth on its own by the filter. Basically if the filter fail to authenticate the request (that matches allowFailedMatchers) or any reasons, it should forward to upstream and let upstream to decide what to do with the unauthenticated request.

If we redirect to OAuth server to start a new oauth flow for these requests, the filter is still enforcing authentication.

This commit addresses a security vulnerability where malicious clients could inject x-envoy-oauth-status and x-envoy-oauth-failure-reason headers that might confuse downstream services about the authentication state of requests. Changes: - Sanitize OAuth status headers (x-envoy-oauth-status and x-envoy-oauth-failure-reason) for all incoming requests in decodeHeaders(), following the same pattern as Authorization header sanitization - Change from addCopy() to setCopy() when setting these headers in continueAsUnauthorized() to ensure headers are replaced rather than appended, providing defense-in-depth - Add test coverage for header injection scenarios in both authenticated and allow_failed code paths The sanitization ensures that only the OAuth2 filter itself can set these headers, preventing header injection attacks at system boundaries. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Signed-off-by: Mo Chen <carterchen.m@gmail.com>

# Conflicts: # changelogs/current.yaml Signed-off-by: Mo Chen <carterchen.m@gmail.com>

The previous merge incorrectly reordered changelog entries alphabetically, causing them to appear as additions in the PR diff. This commit fixes the merge by: - Keeping all main branch entries in their exact original order - Appending the oauth2 allow_failed_matcher entry at the end This minimizes diff noise and makes the PR review clearer. Signed-off-by: Mo Chen <carterchen.m@gmail.com>

mchen391 · 2026-02-04T20:57:30Z

@zhaohuabing, sorry for the ping, but I could use another look at the PR. Changes have been made to the header sanitization per the suggestions, though there are a few other comments I think are worth discussing. Thank you!

mchen391 requested review from mattklein123 and wbpcode as code owners January 16, 2026 01:41

repokitteh-read-only bot added the api label Jan 16, 2026

repokitteh-read-only bot assigned markdroth Jan 16, 2026

mchen391 commented Jan 16, 2026

View reviewed changes

tyxia assigned zhaohuabing Jan 16, 2026

nezdolik assigned wbpcode Jan 27, 2026

repokitteh-read-only bot removed the api label Jan 28, 2026

zhaohuabing reviewed Jan 28, 2026

View reviewed changes

source/extensions/filters/http/oauth2/filter.cc Outdated Show resolved Hide resolved

zhaohuabing reviewed Jan 28, 2026

View reviewed changes

source/extensions/filters/http/oauth2/filter.cc Show resolved Hide resolved

zhaohuabing reviewed Jan 28, 2026

View reviewed changes

mchen391 added 3 commits January 29, 2026 01:34

Merge branch 'main' into oauth2-allow-failed-matcher

fe169c6

# Conflicts: # changelogs/current.yaml Signed-off-by: Mo Chen <carterchen.m@gmail.com>

Conversation

mchen391 commented Jan 16, 2026

Uh oh!

repokitteh-read-only bot commented Jan 16, 2026

Uh oh!

repokitteh-read-only bot commented Jan 16, 2026

Uh oh!

mchen391 Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

tyxia commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zhaohuabing commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mchen391 commented Jan 19, 2026 via email • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zhaohuabing commented Jan 27, 2026

Uh oh!

mchen391 commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

zhaohuabing commented Jan 28, 2026

Uh oh!

markdroth commented Jan 28, 2026

Uh oh!

zhaohuabing Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mchen391 Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

zhaohuabing Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

mchen391 Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zhaohuabing Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

mchen391 Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mchen391 commented Feb 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

tyxia commented Jan 16, 2026 •

edited

Loading

zhaohuabing commented Jan 19, 2026 •

edited

Loading

mchen391 commented Jan 19, 2026 via email •

edited

Loading

mchen391 commented Jan 27, 2026 •

edited

Loading

zhaohuabing Jan 28, 2026 •

edited

Loading

mchen391 Jan 28, 2026 •

edited

Loading

mchen391 Jan 28, 2026 •

edited

Loading

mchen391 Jan 28, 2026 •

edited

Loading