The OAuth2 Filter Type (v1alpha1)

The OAuth2 Filter type performs OAuth2 authorization against an identity provider implementing OIDC Discovery.

This doc is an overview of all the fields on the OAuth2 Filter Custom Resource with descriptions of the purpose, type, and default values of those fields. This page is specific to the gateway.getambassador.io/v1alpha1 version of the OAuth2 Filter resource. For the older getambassador.io/v3alpha1 resource, please see the v3alpha1 OAuth2 Filter api reference.

OAuth2 Filter API Reference

To create an OAuth2 Filter, the spec.type must be set to oauth2, and the oauth2 field must contain the configuration for your OAuth2 filter.

OAuth2Filter

grantType options:

• "AuthorizationCode": Authenticate by redirecting to a login page served by the identity provider.
• "Password": Authenticate by requiring X-Ambassador-Username and X-Ambassador-Password on all incoming requests, and use them to authenticate with the identity provider using the OAuth2 Resource Owner Password Credentials grant type.
• "ClientCredentials": Authenticate by requiring that the incoming HTTP request include as headers the credentials for Ambassador to use to authenticate to the identity provider.
  • The type of credentials needing to be submitted depends on the clientAuthentication.method (below):
  • For "HeaderPassword" and "BodyPassword", the headers X-Ambassador-Client-ID and X-Ambassador-Client-Secret must be set.
  • For "JWTAssertion", the X-Ambassador-Client-Assertion header must be set to a JWT that is signed by your client secret, and conforms with the requirements in RFC 7521 section 5.2 and RFC 7523 section 3, as well as any additional specified by your identity provider.

accessTokenValidation options:

• "jwt": Validates the Access Token as a JWT.

  • By default: It accepts the RS256, RS384, or RS512 signature algorithms, and validates the signature against the JWKS from OIDC Discovery. It then validates the exp, iat, nbf, iss (with the Issuer from OIDC Discovery), and scope claims: if present, none of the scope values are required to be present. This relies on the identity provider using non-encrypted signed JWTs as Access Tokens, and configuring the signing appropriately
  • This behavior can be modified by delegating to JWT Filter with accessTokenJWTFilter:

• "userinfo": Validates the access token by polling the OIDC UserInfo Endpoint. This means that Ambassador Edge Stack must initiate an HTTP request to the identity provider for each authorized request to a protected resource. This performs poorly, but functions properly with a wider range of identity providers. It is not valid to set accessTokenJWTFilter if accessTokenValidation: userinfo.

• "auto" attempts to do "jwt" validation if any of these conditions are true:

  • accessTokenJWTFilter is set
  • grantType is "ClientCredentials"
  • the Access Token parses as a JWT and the signature is valid,
  • If none of the above conditions are satisfied, it falls back to "userinfo" validation.

Duration

Appears on: Oauth2Filter, JWTAssertion, AuthorizationCodeSettings Duration is a field that accepts a string that will be parsed as a sequence of decimal numbers (metav1.Duration), each with optional fraction and a unit suffix, such as "300ms", "1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". See Go time.ParseDuration.

AddHeaderTemplate

Appears On: OAuth2Filter List of headers that will be injected into the upstream request if allowed through. The headers can pull information from the Token has values. For example, attaching user email claim to a header from the token.

The header value can be set based on the JWT value. If an OAuth2 Filter is chained with a JWT filter with injectRequestHeaders configured, both sets of headers will be injected. If the same header is injected in both filters, the OAuth2 Filter will populate the value. The value is specified as a [Go text/template][] string, with the following data made available to it:

• .token.Raw → The access token raw JWT (string)
• .token.Header → The access token JWT header (as parsed JSON: map[string]interface{})
• .token.Claims → The access token JWT claims (as parsed JSON: map[string]interface{})
• .token.Signature → The access token signature (string)
• .idToken.Raw → The raw id token JWT (string)
• .idToken.Header → The id token JWT header (as parsed JSON: map[string]interface{})
• .idToken.Claims → The id token JWT claims (as parsed JSON: map[string]interface{})
• .idToken.Signature → The id token signature (string)
• .httpRequestHeader → http.Header a copy of the header of the incoming HTTP request. Any changes to .httpRequestHeader (such as by using using .httpRequestHeader.Set) have no effect. It is recommended to use .httpRequestHeader.Get instead of treating it as a map, in order to handle capitalization correctly.

JWTFilterReference

Appears On: OAuth2Filter Reference to a JWT Filter to be executed after the OAuth2 Filter finishes

JWTArguments

Appears On: JWTFilterReference Defines the input arguments that can be set for a JWTFilter.

Some notes about scope:

• If grantType: "AuthorizationCode", then the openid scope value is always included in the requested scope, even if it is not listed.
• If grantType: "ClientCredentials" or grantType: "Password", then the default scope is empty. If your identity provider does not have a default scope, then you will need to configure one here.
• As a special case, if the offline_access scope value is requested, but not included in the response then access is not forbidden. With many identity providers, requesting the offline_access scope is necessary to receive a Refresh Token.
• The ordering of scope values does not matter, and is ignored.

ClientAuthentication

Appears On: OAuth2Filter Defines how the OAuth2 Filter will authenticate with the iDP token endpoint. By default, it will pass it along as password in the Authentication header. Depending on how your iDP is configured it might require a JWTAssertion or passing the password.

method options:

• "HeaderPassword": Treat the client secret as a password, and pack that in to an HTTP header for HTTP Basic authentication.
• "BodyPassword": Treat the client secret as a password, and put that in the HTTP request bodies submitted to the identity provider. This is NOT RECOMMENDED by RFC 6749, and should only be used when using HeaderPassword isn't possible.
• "JWTAssertion": Treat the client secret as a password, and put that in the HTTP request bodies submitted to the identity provider. This is NOT RECOMMENDED by RFC 6749, and should only be used when using HeaderPassword isn't possible.

JWTAssertion

Appears On: ClientAuthentication Allows setting a JWT Filter with custom settings on how to verify JWT obtained via the OAuth2 flow.

ValidAlgorithms

Appears On: JWTAssertion Valid Algorithms is an enum with quite a few entries, the possible values are:

• "none"
• ECDSA Algorithms: "ES256", "ES384", "ES512"
  • The secret must be a PEM-encoded Eliptic Curve private key
• HMAC-SHA Algorithms: "HS256", "HS384", "HS512"
  • The secret is a raw string of bytes; it can contain anything
• RSA-PSS Algorithms: "PS256", "PS384", "PS512"
  • The secret must be a PEM-encoded RSA private key
• RSA Algorithms: "RS256", "RS384", "RS512"
  • The secret must be a PEM-encoded RSA private key

AuthorizationCodeSettings

Appears On: OAuth2Filter Specific settings that configure the AuthorizationCode grant type.

Note: If you provide more than one protectedOrigin, all share the same authentication system, so that logging into one origin logs you into all origins; to have multiple domains that have separate logins, use separate Filters.

SecretReference

Appears On: AuthorizationCodeSettings, PasswordSettings, ResourceOwnerSettings A reference to a Kubernetes Secret.

Origin

Appears On: AuthorizationCodeSettings A domain that the OAuth2 Filter is configured to protect. It is recommended that all protected origins are registered with the IdentityProvider because this is subject to change in the future.

Note about allowedInternalOrigins: This field is primarily used to allow you to tell Ambassador Edge Stack that there is another gateway in front of Ambassador Edge Stack that rewrites the Host header, so that on the internal network between that gateway and Ambassador Edge Stack, the origin appears to be allowedInternalOrigins instead of origin. As a special-case the scheme and/or authority of the allowedInternalOrigins may be "*", which matches any scheme or any domain respectively. Using "*" is most useful in configurations with exactly one protected origin; in such a configuration, Ambassador Edge Stack doesn't need to know what the origin looks like on the internal network, just that a gateway in front of Ambassador Edge Stack is rewriting it. It is invalid to use "*" with includeSubdomains: true.

For example, if you have a gateway in front of Ambassador Edge Stack handling traffic for myservice.example.com, terminating TLS and routing that traffic to Ambassador with the name ambassador.internal, you might write:

or, to avoid being fragile to renaming ambassador.internal to something else, since there are not multiple origins that the Filter must distinguish between, you could instead write:

ResourceOwnerSettings

Appears On: OAuth2Filter Specific settings that configure the ResourceOwner grant type.

PasswordSettings

Appears On: OAuth2Filter Specific settings that configure the Password grant type.

PKCEOptions

Appears On AuthorizationCodeSettings