Filter Type: JWT

The JWT filter type performs JWT validation on a Bearer token present in the HTTP header. If the Bearer token JWT doesn't validate, or has insufficient scope, an RFC 6750-complaint error response with a WWW-Authenticate header is returned. The list of acceptable signing keys is loaded from a JWK Set that is loaded over HTTP, as specified in jwksURI. Only RSA and none algorithms are supported.

JWT Global Arguments

• insecureTLS disables TLS verification for the cases when jwksURI begins with https://. This is discouraged in favor of either using plain http:// or installing a self-signed certificate.

• renegotiateTLS allows a remote server to request TLS renegotiation. Accepted values are "never", "onceAsClient", and "freelyAsClient".

• injectRequestHeaders injects HTTP header fields in to the request before sending it to the upstream service; where the header value can be set based on the JWT value. The value is specified as a [Gotext/template][] string, with the following data made available to it:

  • .token.Raw → string the raw JWT
  • .token.Header → map[string]interface{} the JWT header, as parsed JSON
  • .token.Claims → map[string]interface{} the JWT claims, as parsed JSON
  • .token.Signature → string the token signature
  • .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.

  Any headers listed will override (not append to) the original request header with that name.

• errorResponse allows templating the error response, overriding the default json error format. Make sure you validate and test your template, not to generate server-side errors on top of client errors.

  • contentType is deprecated, and is equivalent to including a name: "Content-Type" item in headers.

  • realm allows specifying the realm to report in the WWW-Authenticate response header.

  • headers sets extra HTTP header fields in the error response. The value is specified as a Go text/template string, with the same data made available to it as bodyTemplate (below). It does not have access to the json function.

  • bodyTemplate specifies body of the error; specified as a [Gotext/template][] string, with the following data made available to it:

    • .status_code → integer the HTTP status code to be returned
    • .httpStatus → integer an alias for .status_code (hidden from {{ . | json "" }})
    • .message → string the error message string
    • .error → error the raw Go error object that generated .message (hidden from {{ . | json "" }})
    • .error.ValidationError → jwt.ValidationError the JWT validation error, will be nil if the error is not purely JWT validation (insufficient scope, malformed or missing Authorization header)
    • .request_id → string the Envoy request ID, for correlation (hidden from {{ . | json "" }} unless .status_code is in the 5XX range)
    • .requestId → string an alias for .request_id (hidden from {{ . | json "" }})

    In addition to the standard functions available to Go text/templates, there is a json function that arg2 as JSON, using the arg1 string as the starting indent level.

Note: If you are using a templating system for your YAML that also makes use of Go templating, then you will need to escape the template strings meant to be interpreted by the Ambassador Edge Stack.

JWT Path-Specific Arguments

• scope: A list of OAuth scope values that Ambassador will require to be listed in the scope claim. In addition to the normal of the scope claim (a JSON string containing a space-separated list of values), the JWT Filter also accepts a JSON array of values.

Example JWT Filter