The OAuth2 Filter Type (v3alpha1)

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 getambassador.io/v3alpha1 version of the OAuth2 Filter resource. For the newer gateway.getambassador.io/v1alpha1 resource, please see the v1alpha1 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

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.

ClientAuthentication

Configures how Ambassador uses the clientID and secret to authenticate itself to the identity provider

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

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

ValidAlgorithms

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

ProtectedOrigin

You determine these, and must register them with your identity provider. Identifies hostnames that can appropriately set cookies for the application. Only the scheme (https://) and authority (example.com:1234) parts are used; the path part of the URL is ignored. You will need to register each origin in protectedOrigins as an authorized callback endpoint with your identity provider. The URL will look like {{ORIGIN}}/.ambassador/oauth2/redirection-endpoint.

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.

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 Edge Stack with the name example.internal, you might write:

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

AddHeaderTemplate

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.

SessionCookies

By default, any cookies set by the Ambassador Edge Stack will be set to expire when the session expires naturally. The useSessionCookies setting may be used to cause session cookies to be used instead.

• Normally cookies are set to be deleted at a specific time; session cookies are deleted whenever the user closes their web browser. This may mean that the cookies are deleted sooner than normal if the user closes their web browser; conversely, it may mean that cookies persist for longer than normal if the use does not close their browser.
• The cookies being deleted sooner may or may not affect user-perceived behavior, depending on the behavior of the identity provider.
• Any cookies persisting longer will not affect behavior of the system; Ambassador Edge Stack validates whether the session is expired when considering the cookie.

If useSessionCookies is non-null, then:

• By default it will have the cookies for all requests be session cookies or not according to the useSessionCookies.value sub-argument.
• Setting the useSessionCookies.ifRequestHeader sub-argument tells it to use useSessionCookies.value for requests that match the condition, and !useSessionCookies.value for requests don't match.

When determining if a request matches, it looks at the HTTP header field named by useSessionCookies.ifRequestHeader.name (case-insensitive), and checks if it is either set to (if useSessionCookies.ifRequestHeader.negate: false) or not set to (if useSessionCookies.ifRequestHeader.negate: true)...

• a non-empty string (if neither useSessionCookies.ifRequestHeader.value nor useSessionCookies.ifRequestHeader.valueRegex are set)
• the exact string value (case-sensitive) (if useSessionCookies.ifRequestHeader.value is set)
• a string that matches the regular expression useSessionCookies.ifRequestHeader.valueRegex (if valueRegex is set). This uses RE2 syntax (always, not obeying regex_type in the Module) but does not support the \C escape sequence.
• (it is invalid to have both value and valueRegex set)

HTTPHeaderMatch

Checks if exact or regular expression matches a value in a request Header to determine if an individual Filter is executed or not.

AccessTokenJWTFilter

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

JWTArguments

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.