Handling a failed OAuth flow gracefully

[pylaligand]

Hi there,

I'm using a SecurityPolicy to automatically start an OIDC flow when users hit some private HTTP routes. When access gets denied, I'm redirected to https://my.domain/oauth2/callback?error=access_denied&error_description=some-text&state=some-gibberish which displays an empty page with this text:

OAuth flow failed.

Is there a way to customize what happens on OAuth failure, for example redirecting to some URL? There are legitimate cases where my users will get denied and I'd like to handle them gracefully.

Cheers,
=py=

[arkodg]

you could redirect using a response override https://gateway.envoyproxy.io/docs/tasks/traffic/response-override/
https://gateway.envoyproxy.io/docs/api/extension_types/#responseoverride

[pylaligand]

Thanks for the suggestion.

When I configure a responseOverride with a response, I get the expected behavior. However, when I use a redirect nothing happens. Here's the relevant snippet in the BackendTrafficPolicy:

  responseOverride:
    - match:
        statusCodes:
          - type: Value
            value: 401
      redirect:
        path:
          type: ReplaceFullPath
          replaceFullPath: "/logout"
        statusCode: 302

With the relevant logs from the gateway pod:

[2025-12-16 10:24:47.173][125][warning][oauth2] [source/extensions/filters/http/oauth2/filter.cc:1281] Responding with 401 Unauthorized. Cause: OAuth server returned an error: ?error=access_denied&error_description=Failed&state=<some value>
{
    ":authority": "my.domain",
    "bytes_received": 0,
    "bytes_sent": 18,
    "connection_termination_details": null,
    "downstream_local_address": "ip:port",
    "downstream_remote_address": "ip:port",
    "duration": 0,
    "method": "GET",
    "protocol": "HTTP/2",
    "requested_server_name": "my.domain",
    "response_code": 401,
    "response_code_details": "OAuth_server_returned_an_error:_?error=access_denied&error_description=Failed&state=<some value>",
    "response_flags": "-",
    "route_name": "httproute/my-namespace/my-route/rule/0/match/0/my_domain",
    "start_time": "2025-12-16T10:24:47.173Z",
    "upstream_cluster": "httproute/my-namespace/my-route/rule/0",
    "upstream_host": null,
    "upstream_local_address": null,
    "upstream_transport_failure_reason": null,
    "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
    "x-envoy-origin-path": "/oauth2/callback?error=access_denied&error_description=Failed!&state=<some value>",
    "x-envoy-upstream-service-time": null,
    "x-forwarded-for": "ip",
    "x-request-id": "72513577-d1cb-46cd-980c-e8a8e31a694a"
}

Any idea what's going on?

[arkodg]

cc @zhaohuabing

[pylaligand]

Relevant Slack thread: https://envoyproxy.slack.com/archives/C03E6NHLESV/p1763998394192029