OAuth (proto)
This extension has the qualified name envoy.filters.http.oauth2
Note
This extension is functional but has not had substantial production burn time, use only with this caveat.
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:
This extension must be configured with one of the following type URLs:
OAuth configuration overview.
extensions.filters.http.oauth2.v3.OAuth2Credentials
[extensions.filters.http.oauth2.v3.OAuth2Credentials proto]
{
"client_id": ...,
"token_secret": {...},
"hmac_secret": {...},
"cookie_names": {...}
}
- 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, REQUIRED) The secret used to retrieve the access token. This value will be URL encoded when sent to the OAuth server.
- 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.
- cookie_names
(extensions.filters.http.oauth2.v3.OAuth2Credentials.CookieNames) The cookie names used in OAuth filters flow.
extensions.filters.http.oauth2.v3.OAuth2Config
[extensions.filters.http.oauth2.v3.OAuth2Config proto]
OAuth config
{
"token_endpoint": {...},
"authorization_endpoint": ...,
"credentials": {...},
"redirect_uri": ...,
"redirect_path_matcher": {...},
"signout_path": {...},
"forward_bearer_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": ...
}
- token_endpoint
(config.core.v3.HttpUri) Endpoint on the authorization server to retrieve the access token from.
- authorization_endpoint
(string, REQUIRED) The endpoint redirect to for authorization in response to unauthorized requests.
- 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.
- preserve_authorization_header
(bool) If set to true, preserve the existing authorization header. By default Envoy 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
andclient_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 false.
- 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 ifuse_refresh_token
is set to true, otherwise the authorization server expiration ordefaul_expires_in
is used.
- disable_id_token_set_cookie
(bool) If set to true, Envoy will not set a cookie for ID Token even if one is received from the Identity Provider. This may be useful in cases where the ID Token is too large for HTTP cookies (longer than 4096 characters). Enabling this option will only disable setting the cookie response header, the filter will still process incoming ID Tokens as part of the HMAC if they are there. This is to ensure compatibility while switching this setting on. Future sessions would not set the IdToken cookie header.
Enum extensions.filters.http.oauth2.v3.OAuth2Config.AuthType
[extensions.filters.http.oauth2.v3.OAuth2Config.AuthType proto]
- URL_ENCODED_BODY
(DEFAULT) The
client_id
andclient_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
andclient_secret
will be sent using HTTP Basic authentication scheme.
extensions.filters.http.oauth2.v3.OAuth2
[extensions.filters.http.oauth2.v3.OAuth2 proto]
Filter config.
{
"config": {...}
}
- config
(extensions.filters.http.oauth2.v3.OAuth2Config) Leave this empty to disable OAuth2 for a specific route, using per filter config.