OAuth (proto)

This extension has the qualified name envoy.filters.http.oauth2

Note

This extension is intended to be robust against untrusted downstream traffic. It assumes that the upstream is trusted.

Tip

This extension extends and can be used with the following extension category:

envoy.filters.http

This extension must be configured with one of the following type URLs:

type.googleapis.com/envoy.extensions.filters.http.oauth2.v3.OAuth2
type.googleapis.com/envoy.extensions.filters.http.oauth2.v3.OAuth2PerRoute

OAuth configuration overview.

extensions.filters.http.oauth2.v3.CookieConfig

[extensions.filters.http.oauth2.v3.CookieConfig proto]

OAuth cookie configuration attributes.

{
  "same_site": ...,
  "path": ...,
  "partitioned": ...
}

same_site: (extensions.filters.http.oauth2.v3.CookieConfig.SameSite) The value used for the SameSite cookie attribute.

path

(string) The path attribute for the cookie.

This controls the scope of the cookie and is useful for path-based routing scenarios where different logical boundaries or applications may operate with different OAuth2 clients. The CSRF cookie (nonce cookie) can be configured with a different path than session cookies to support flows where the callback URL is on a different path.

If not specified, defaults to /.

partitioned

(bool) If true, the Partitioned attribute will be set on the cookie.

Modern browsers (Firefox, Chrome with third-party cookie deprecation) warn or block “foreign” cookies unless they carry the Partitioned attribute alongside SameSite=None; Secure. When Envoy is used in a gateway/IdP flow that sets OAuth/OIDC cookies for a parent domain (e.g., Domain=.example.com) while running on a different host, those cookies are considered third-party and will be rejected without Partitioned.

See CHIPS for more information.

Default is false.

Enum extensions.filters.http.oauth2.v3.CookieConfig.SameSite

[extensions.filters.http.oauth2.v3.CookieConfig.SameSite proto]

DISABLED: (DEFAULT) ⁣

STRICT: ⁣

LAX: ⁣

NONE: ⁣

extensions.filters.http.oauth2.v3.CookieConfigs

[extensions.filters.http.oauth2.v3.CookieConfigs proto]

{
  "bearer_token_cookie_config": {...},
  "oauth_hmac_cookie_config": {...},
  "oauth_expires_cookie_config": {...},
  "id_token_cookie_config": {...},
  "refresh_token_cookie_config": {...},
  "oauth_nonce_cookie_config": {...},
  "code_verifier_cookie_config": {...}
}

extensions.filters.http.oauth2.v3.OAuth2Credentials

[extensions.filters.http.oauth2.v3.OAuth2Credentials proto]

{
  "client_id": ...,
  "token_secret": {...},
  "hmac_secret": {...},
  "cookie_names": {...},
  "cookie_domain": ...
}

client_id: (string, REQUIRED) The client_id to be used in the authorize calls. This value will be URL encoded when sent to the OAuth server.

token_secret: (extensions.transport_sockets.tls.v3.SdsSecretConfig) The secret used to retrieve the access token. This value will be URL encoded when sent to the OAuth server. This field is required unless auth_type is set to TLS_CLIENT_AUTH, in which case authentication is done via the client certificate. When auth_type is PRIVATE_KEY_JWT, this field must contain the PEM-encoded private key used to sign the JWT client assertion.

hmac_secret

(extensions.transport_sockets.tls.v3.SdsSecretConfig, REQUIRED) If present, the secret token will be a HMAC using the provided secret.

Configures how the secret token should be created.

extensions.filters.http.oauth2.v3.OAuth2Credentials.CookieNames

[extensions.filters.http.oauth2.v3.OAuth2Credentials.CookieNames proto]

{
  "bearer_token": ...,
  "oauth_hmac": ...,
  "oauth_expires": ...,
  "id_token": ...,
  "refresh_token": ...,
  "oauth_nonce": ...,
  "code_verifier": ...
}

bearer_token: (string) Cookie name to hold OAuth bearer token value. When the authentication server validates the client and returns an authorization token back to the OAuth filter, no matter what format that token is, if forward_bearer_token is set to true the filter will send over the bearer token as a cookie with this name to the upstream. Defaults to BearerToken.

oauth_hmac: (string) Cookie name to hold OAuth HMAC value. Defaults to OauthHMAC.

oauth_expires: (string) Cookie name to hold OAuth expiry value. Defaults to OauthExpires.

id_token: (string) Cookie name to hold the id token. Defaults to IdToken.

refresh_token: (string) Cookie name to hold the refresh token. Defaults to RefreshToken.

oauth_nonce: (string) Cookie name to hold the nonce value. Defaults to OauthNonce.

code_verifier: (string) Cookie name to hold the PKCE code verifier. Defaults to OauthCodeVerifier.

extensions.filters.http.oauth2.v3.PrivateKeyJwtConfig

[extensions.filters.http.oauth2.v3.PrivateKeyJwtConfig proto]

Configuration for PRIVATE_KEY_JWT client authentication (RFC 7523).

{
  "signing_algorithm": ...,
  "assertion_lifetime": {...}
}

signing_algorithm: (extensions.filters.http.oauth2.v3.PrivateKeyJwtConfig.SigningAlgorithm) The signing algorithm to use for the JWT assertion. The private key provided in token_secret must match the algorithm family: an RSA key for the RS* algorithms, or an EC key for the ES* algorithms. Default: RS256.

assertion_lifetime: (Duration) The lifetime of the JWT assertion. After this duration, the assertion expires. The value is truncated to whole seconds, so it must be at least 1s when set. Default: 60s.

Enum extensions.filters.http.oauth2.v3.PrivateKeyJwtConfig.SigningAlgorithm

[extensions.filters.http.oauth2.v3.PrivateKeyJwtConfig.SigningAlgorithm proto]

Supported JWT signing algorithms for the client assertion.

RS256: (DEFAULT) ⁣``RSASSA-PKCS1-v1_5`` using SHA-256.

RS384: ⁣``RSASSA-PKCS1-v1_5`` using SHA-384.

RS512: ⁣``RSASSA-PKCS1-v1_5`` using SHA-512.

ES256: ⁣ECDSA using P-256 and SHA-256.

ES384: ⁣ECDSA using P-384 and SHA-384.

ES512: ⁣ECDSA using P-521 and SHA-512.

extensions.filters.http.oauth2.v3.OAuth2TokenForwarding

[extensions.filters.http.oauth2.v3.OAuth2TokenForwarding proto]

Defines how an OAuth token is forwarded upstream.

{
  "header": ...
}

header: (string, REQUIRED) The upstream request header that will carry the token. Pseudo-headers (names starting with :) and the Host header are not allowed.

extensions.filters.http.oauth2.v3.PostLogoutRedirectUri

[extensions.filters.http.oauth2.v3.PostLogoutRedirectUri proto]

Configuration for the post_logout_redirect_uri parameter used in OpenID Connect RP-Initiated Logout requests. This configuration is ignored if end_session_endpoint is not set.

{
  "disabled": ...,
  "uri": ...
}

disabled

(bool) Do not include the post_logout_redirect_uri parameter in requests to the configured end_session_endpoint.

Precisely one of disabled, uri must be set.

uri

(string) URI to send as the post_logout_redirect_uri parameter. Supports header formatting tokens, and will be percent-encoded automatically when building the logout URL.

The URI should be registered with the authorization server.

Precisely one of disabled, uri must be set.

extensions.filters.http.oauth2.v3.OAuth2Config

[extensions.filters.http.oauth2.v3.OAuth2Config proto]

OAuth config

{
  "token_endpoint": {...},
  "retry_policy": {...},
  "authorization_endpoint": ...,
  "end_session_endpoint": ...,
  "post_logout_redirect_uri": {...},
  "credentials": {...},
  "redirect_uri": ...,
  "redirect_path_matcher": {...},
  "signout_path": {...},
  "forward_bearer_token": ...,
  "forward_id_token": {...},
  "preserve_authorization_header": ...,
  "pass_through_matcher": [],
  "auth_scopes": [],
  "resources": [],
  "auth_type": ...,
  "use_refresh_token": {...},
  "default_expires_in": {...},
  "deny_redirect_matcher": [],
  "default_refresh_token_expires_in": {...},
  "disable_id_token_set_cookie": ...,
  "disable_access_token_set_cookie": ...,
  "disable_refresh_token_set_cookie": ...,
  "cookie_configs": {...},
  "stat_prefix": ...,
  "csrf_token_expires_in": {...},
  "code_verifier_token_expires_in": {...},
  "disable_token_encryption": ...,
  "allow_failed_matcher": [],
  "original_request_uri": ...,
  "allowed_redirect_domains": [],
  "use_access_token_expiry_for_id_token_cookie": ...,
  "private_key_jwt_config": {...}
}

token_endpoint: (config.core.v3.HttpUri) Endpoint on the authorization server to retrieve the access token from.

retry_policy: (config.core.v3.RetryPolicy) Specifies the retry policy for requests to the OAuth server. If not specified, then no retries will be performed.

authorization_endpoint: (string, REQUIRED) The endpoint redirect to for authorization in response to unauthorized requests.

end_session_endpoint

(string) The endpoint at the authorization server to request the user be logged out of the Authorization server. This field is optional and should be set only if openid is in the auth_scopes and the authorization server supports the OpenID Connect RP-Initiated Logout specification. For more information, see https://openid.net/specs/openid-connect-rpinitiated-1_0.html

If configured, the OAuth2 filter will redirect users to this endpoint when they access the signout_path.

post_logout_redirect_uri

(extensions.filters.http.oauth2.v3.PostLogoutRedirectUri) Optional control for the post_logout_redirect_uri parameter sent to the end_session_endpoint when a user accesses the signout_path. This field should be set only if openid is in the auth_scopes, the end_session_endpoint is configured, and the authorization server supports the OpenID Connect RP-Initiated Logout specification.

If unset, Envoy preserves the historical behavior and sends <scheme>://<host>/, constructed from the inbound request, as post_logout_redirect_uri.

credentials: (extensions.filters.http.oauth2.v3.OAuth2Credentials, REQUIRED) Credentials used for OAuth.

redirect_uri

(string, REQUIRED) The redirect URI passed to the authorization endpoint. Supports header formatting tokens. For more information, including details on header value syntax, see the documentation on custom request headers.

This URI should not contain any query parameters.

redirect_path_matcher: (type.matcher.v3.PathMatcher, REQUIRED) Matching criteria used to determine whether a path appears to be the result of a redirect from the authorization server.

signout_path: (type.matcher.v3.PathMatcher, REQUIRED) The path to sign a user out, clearing their credential cookies.

forward_bearer_token: (bool) Forward the OAuth token as a Bearer to upstream web service.

forward_id_token

(extensions.filters.http.oauth2.v3.OAuth2TokenForwarding) Forward the OIDC ID token to the upstream.

If the configured header is Authorization, Envoy forwards the ID token using the Bearer prefix. For any other header, Envoy forwards the raw token value. If not specified, the ID token will not be forwarded.

This can not be configured with forward_bearer_token or preserve_authorization_header when the header is Authorization.

preserve_authorization_header: (bool) If set to true, preserve the existing authorization header. By default the client strips the existing authorization header before forwarding upstream. Can not be set to true if forward_bearer_token is already set to true. Default value is false.

pass_through_matcher: (repeated config.route.v3.HeaderMatcher) Any request that matches any of the provided matchers will be passed through without OAuth validation.

auth_scopes: (repeated string) Optional list of OAuth scopes to be claimed in the authorization request. If not specified, defaults to “user” scope. OAuth RFC https://tools.ietf.org/html/rfc6749#section-3.3

resources: (repeated string) Optional resource parameter for authorization request RFC: https://tools.ietf.org/html/rfc8707

auth_type: (extensions.filters.http.oauth2.v3.OAuth2Config.AuthType) Defines how client_id and client_secret are sent in OAuth client to OAuth server requests. RFC https://datatracker.ietf.org/doc/html/rfc6749#section-2.3.1

use_refresh_token: (BoolValue) If set to true, allows automatic access token refresh using the associated refresh token (see RFC 6749 section 6), provided that the OAuth server supports that. Default value is true.

default_expires_in

(Duration) The default lifetime in seconds of the access token, if omitted by the authorization server.

If this value is not set, it will default to 0s. In this case, the expiry must be set by the authorization server or the OAuth flow will fail.

deny_redirect_matcher: (repeated config.route.v3.HeaderMatcher) Any request that matches any of the provided matchers won’t be redirected to OAuth server when tokens are not valid. Automatic access token refresh will be performed for these requests, if enabled. This behavior can be useful for AJAX requests.

default_refresh_token_expires_in

(Duration) The default lifetime in seconds of the refresh token, if the exp (expiration time) claim is omitted in the refresh token or the refresh token is not JWT.

If this value is not set, it will default to 604800s. In this case, the cookie with the refresh token will be expired in a week. This setting is only considered if use_refresh_token is set to true, otherwise the authorization server expiration or default_expires_in is used.

stat_prefix: (string) Optional additional prefix to use when emitting statistics.

csrf_token_expires_in: (Duration) Optional expiration time for the CSRF protection token cookie. The CSRF token prevents cross-site request forgery attacks during the OAuth2 flow. If not specified, defaults to 600s (10 minutes), which should provide sufficient time for users to complete the OAuth2 authorization flow.

code_verifier_token_expires_in: (Duration) Optional expiration time for the code verifier cookie. The code verifier is stored in a secure, HTTP-only cookie during the OAuth2 authorization process. If not specified, defaults to 600s (10 minutes), which should provide sufficient time for users to complete the OAuth2 authorization flow.

disable_token_encryption: (bool) Disable token encryption. When set to true, both the access token and the ID token will be stored in plain text. This option should only be used in secure environments where token encryption is not required. Default is false (tokens are encrypted).

allow_failed_matcher

(repeated config.route.v3.HeaderMatcher) Any request that matches any of the provided matchers will be allowed to continue to upstream even if OAuth validation fails (missing, invalid, or expired credentials). This is useful for services that can handle both authenticated and unauthenticated requests, enabling graceful degradation patterns.

When triggered, all OAuth cookies are stripped from the request and the request proceeds as unauthenticated. Context headers x-envoy-oauth-status: failed and x-envoy-oauth-failure-reason are added to inform upstream.

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.

original_request_uri

(string) Optional base URI (scheme + host, e.g. https://app.example.com) used to build the original request URI that is encoded into the OAuth2 state parameter. This URI will be used later to redirect users on a successful OAuth.

This is useful when Envoy sits behind a gateway or load balancer that terminates the user-facing hostname: In that case, the post-authentication redirect derived from state would send the user to an internal host they didn’t request.

Supports request header formatting tokens.

Example:

original_request_uri: “%REQ(x-forwarded-proto?:scheme)%://%REQ(x-forwarded-host?:authority)%”

If not set, defaults to <:scheme>://<:authority> of the incoming request.

allowed_redirect_domains

(repeated string) Optional list of domains that are allowed as 1. redirect_uri: which is what the IdP calls after OAuth 2. original_request_uri: the one extracted from the state of an OAuth callback (where should the request go after OAuth)

This mitigates: - injecting a malicious x-forwarded-host or any header that is used to template the redirect urls - open redirect attacks where an attacker crafts a state value pointing to an untrusted host.

Each entry is matched against the host (with any port stripped) extracted from the formatted redirect_uri, the formatted original_request_uri, and the URL decoded from the state parameter on callback. Matching is case-insensitive and supports two forms:

Exact match, e.g. example.com matches only example.com.
Wildcard subdomain match using a leading *., e.g. *.example.com matches foo.example.com and bar.baz.example.com but not example.com itself.

IPv6 literals must be configured without surrounding brackets (e.g. ::1, not [::1]).

If this list is empty (the default), all hosts are allowed and no validation is performed.

private_key_jwt_config: (extensions.filters.http.oauth2.v3.PrivateKeyJwtConfig) Configuration for PRIVATE_KEY_JWT client authentication. Only used when auth_type is set to PRIVATE_KEY_JWT.

Enum extensions.filters.http.oauth2.v3.OAuth2Config.AuthType

[extensions.filters.http.oauth2.v3.OAuth2Config.AuthType proto]

URL_ENCODED_BODY: (DEFAULT) ⁣The client_id and client_secret will be sent in the URL encoded request body. This type should only be used when Auth server does not support Basic authentication.

BASIC_AUTH: ⁣The client_id and client_secret will be sent using HTTP Basic authentication scheme.

TLS_CLIENT_AUTH: ⁣The client will be authenticated using mutual TLS (mTLS) with a client certificate. The client_secret is not required and will not be sent in the request to the authorization server. The client certificate must be configured in the cluster used by token_endpoint via transport socket configuration. This implements OAuth 2.0 Mutual-TLS Client Authentication as defined in RFC 8705.

PRIVATE_KEY_JWT: ⁣The client authenticates using a signed JWT assertion (RFC 7523). The token_secret in credentials must contain the PEM-encoded private key used to sign the assertion. The JWT assertion is sent as client_assertion in the token request body along with client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

extensions.filters.http.oauth2.v3.OAuth2PerRoute

[extensions.filters.http.oauth2.v3.OAuth2PerRoute proto]

Per-route OAuth2 config.

This message supplies an OAuth2Config for the matched route. It overrides the filter-level config for requests matching the route. If neither the global config nor a per-route config is specified, OAuth2 is disabled for the route.

{
  "config": {...}
}

config: (extensions.filters.http.oauth2.v3.OAuth2Config, REQUIRED) Full OAuth2 config for this route.

extensions.filters.http.oauth2.v3.OAuth2

[extensions.filters.http.oauth2.v3.OAuth2 proto]

Filter config.

{
  "config": {...}
}

config: (extensions.filters.http.oauth2.v3.OAuth2Config) The OAuth2 filter config.