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:

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

OAuth configuration overview.

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, 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.

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": ...
}

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.

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

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

OAuth config

{
  "token_endpoint": {...},
  "retry_policy": {...},
  "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": ...,
  "disable_access_token_set_cookie": ...,
  "disable_refresh_token_set_cookie": ...
}

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.

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 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 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 if use_refresh_token is set to true, otherwise the authorization server expiration or default_expires_in is used.

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.

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.