JWT

The jwt block lets you configure JSON Web Token access control for your gateway. Like all access control types, the jwt block is defined in the definitions Block and can be referenced in all configuration blocks by its required label.

Since responses from endpoints protected by JWT access controls are not publicly cacheable, a Cache-Control: private header field is added to the response, unless this feature is disabled with disable_private_caching = true.

Block name	Context	Label
`jwt`	Definitions Block	⚠ required

Attributes

Name	Type	Default	Description
`backend`	string	-	References a backend in definitions for JWKS requests. Mutually exclusive with `backend` block.
`bearer`	bool	`false`	If set to `true` the token is obtained from an `Authorization: Bearer ...` request header. Cannot be used together with `cookie`, `beta_dpop`, `header` or `token_value`.
`beta_dpop`	bool	`false`	If set to `true` the token is obtained from an `Authorization: DPoP ...` request header. Cannot be used together with `bearer`, `cookie`, `header` or `token_value`.
`claims`	object	-	Object with claims that must be given for a valid token (equals comparison with JWT payload). The claim values are evaluated per request.
`cookie`	string	-	Read token value from a cookie. Cannot be used together with `bearer`, `beta_dpop`, `header` or `token_value`
`custom_log_fields`	object	-	Log fields for custom logging. Inherited by nested blocks.
`disable_private_caching`	bool	`false`	If set to `true`, Couper does not add the `private` directive to the `Cache-Control` HTTP header field value.
`header`	string	-	Read token value from the given request header field. Implies `Bearer` if `Authorization` (case-insensitive) is used (deprecated!), otherwise any other header name can be used. Cannot be used together with `bearer`, `cookie`, `beta_dpop` or `token_value`.
`jwks_max_stale`	duration	`"1h"`	Time period the cached JWK set stays valid after its TTL has passed.
`jwks_ttl`	duration	`"1h"`	Time period the JWK set stays valid and may be cached.
`jwks_url`	string	-	URI pointing to a set of JSON Web Keys (RFC 7517)
`key`	string	-	Public key (in PEM format) for `RS` and `ES` variants or the secret for `HS*` algorithm. Mutually exclusive with `key_file`.
`key_file`	string	-	Reference to file containing verification key. Mutually exclusive with `key`. See `key` for more information.
`permissions_claim`	string	-	Name of claim containing the granted permissions. The claim value must either be a string containing a space-separated list of permissions or a list of string permissions.
`permissions_map`	object	-	Mapping of granted permissions to additional granted permissions. Maps values from `permissions_claim` and those created from `roles_map`. The map is called recursively. Mutually exclusive with `permissions_map_file`.
`permissions_map_file`	string	-	Reference to JSON file containing permission mappings. Mutually exclusive with `permissions_map`. See `permissions_map` for more information.
`required_claims`	tuple (string)	`[]`	List of claim names that must be given for a valid token.
`roles_claim`	string	-	Name of claim specifying the roles of the user represented by the token. The claim value must either be a string containing a space-separated list of role values or a list of string role values.
`roles_map`	object	-	Mapping of roles to granted permissions. Non-mapped roles can be assigned with `*` to specific permissions. Mutually exclusive with `roles_map_file`.
`roles_map_file`	string	-	Reference to JSON file containing role mappings. Mutually exclusive with `roles_map`. See `roles_map` for more information.
`signature_algorithm`	string	-	Valid values: `RS256`, `RS384`, `RS512`, `HS256`, `HS384`, `HS512`, `ES256`, `ES384`, `ES512`
`signing_key`	string	-	Private key (in PEM format) for `RS` and `ES` variants. Mutually exclusive with `signing_key_file`.
`signing_key_file`	string	-	Reference to file containing signing key. Mutually exclusive with `signing_key`. See `signing_key` for more information.
`signing_ttl`	duration	-	The token's time-to-live (creates the `exp` claim).
`token_value`	string	-	Expression to obtain the token. Cannot be used together with `bearer`, `cookie`, `beta_dpop` or `header`.

The attributes bearer, cookie, header and token_value are mutually exclusive. If all four attributes are missing, bearer = true will be implied, i.e. the token will be read from the incoming Authorization: Bearer ... header.

Deprecation Note: Configuring header = "Authorization" to read from the incoming Authorization: Bearer ... header is deprecated. Use bearer = true instead.

If the key to verify the signatures of tokens does not change over time, it should be specified via either key or key_file (together with signature_algorithm). Otherwise, a JSON web key set should be referenced via jwks_url; in this case, the tokens need a kid header.

A JWT access control configured by this block can extract permissions from

the value of the claim specified by permissions_claim and
the result of mapping the value of the claim specified by roles_claim using the roles_map.

The jwt block may also be referenced by the jwt_sign() function, if it has a signing_ttl defined. For HS* algorithms the signing key is taken from key/key_file, for RS* and ES* algorithms, signing_key or signing_key_file have to be specified.

Note: A jwt block with signing_ttl cannot have the same label as a jwt_signing_profile block.

Duration

Values of type duration are provided as number string followed by a unit listed below.

Example: timeout = "300s"

Duration units	Description
`ns`	nanoseconds
`us` (or `µs`)	microseconds
`ms`	milliseconds
`s`	seconds
`m`	minutes
`h`	hours

Nested Blocks

Name	Description
`backend`	Configures a backend for JWKS requests (zero or one). Mutually exclusive with `backend` attribute.
`error_handler`	Configures an error handler (zero or more).

< JWT Signing Profile

OAuth2 >