Module ngx_http_auth_jwt_module (original) (raw)
The ngx_http_auth_jwt_module module (1.11.3) implements client authorization by validating the providedJSON Web Token (JWT) using the specified keys. The module supportsJSON Web Signature (JWS),JSON Web Encryption (JWE) (1.19.7), and Nested JWT (1.21.0). The module can be used forOpenID Connectauthentication.
The module may be combined with other access modules, such asngx_http_access_module,ngx_http_auth_basic_module, andngx_http_auth_request_module, via the satisfy directive.
This module is available as part of ourcommercial subscription.
Supported Algorithms
The module supports the following JSON WebAlgorithms.
JWS algorithms:
- HS256, HS384, HS512
- RS256, RS384, RS512
- ES256, ES384, ES512
- EdDSA (Ed25519 and Ed448 signatures) (1.15.7)
Prior to version 1.13.7, only HS256, RS256, ES256 algorithms were supported.
JWE content encryption algorithms (1.19.7):
- A128CBC-HS256, A192CBC-HS384, A256CBC-HS512
- A128GCM, A192GCM, A256GCM
JWE key management algorithms (1.19.9):
- A128KW, A192KW, A256KW
- A128GCMKW, A192GCMKW, A256GCMKW
- dir - direct use of a shared symmetric key as the content encryption key
- RSA-OAEP, RSA-OAEP-256, RSA-OAEP-384, RSA-OAEP-512 (1.21.0)
Example Configuration
location / { auth_jwt "closed site"; auth_jwt_key_file conf/keys.json; }
Directives
| Syntax: | auth_jwt string [token=_$variable_] |off; |
|---|---|
| Default: | auth_jwt off; |
| Context: | http, server, location, limit_except |
Enables validation of JSON Web Token. The specified _string_ is used as a realm. Parameter value can contain variables.
The optional token parameter specifies a variable that contains JSON Web Token. By default, JWT is passed in the “Authorization” header as aBearer Token. JWT may be also passed as a cookie or a part of a query string:
auth_jwt "closed site" token=$cookie_auth_token;
The special value off cancels the effect of the auth_jwt directive inherited from the previous configuration level.
| Syntax: | auth_jwt_claim_set $variable name ...; |
|---|---|
| Default: | — |
| Context: | http |
This directive appeared in version 1.11.10.
Sets the _variable_ to a JWT claim parameter identified by key names. Name matching starts from the top level of the JSON tree. For arrays, the variable keeps a list of array elements separated by commas.
auth_jwt_claim_set $email info e-mail; auth_jwt_claim_set $job info "job title";
Prior to version 1.13.7, only one key name could be specified, and the result was undefined for arrays.
Variable values for tokens encrypted with JWE are available only after decryption which occurs during theAccess phase.
| Syntax: | auth_jwt_header_set $variable name ...; |
|---|---|
| Default: | — |
| Context: | http |
This directive appeared in version 1.11.10.
Sets the _variable_ to a JOSE header parameter identified by key names. Name matching starts from the top level of the JSON tree. For arrays, the variable keeps a list of array elements separated by commas.
Prior to version 1.13.7, only one key name could be specified, and the result was undefined for arrays.
| Syntax: | auth_jwt_key_cache time; |
|---|---|
| Default: | auth_jwt_key_cache 0; |
| Context: | http, server, location |
This directive appeared in version 1.21.4.
Enables or disables caching of keys obtained from a fileor from a subrequest, and sets caching time for them. Caching of keys obtained from variables is not supported. By default, caching of keys is disabled.
| Syntax: | auth_jwt_key_file file; |
|---|---|
| Default: | — |
| Context: | http, server, location, limit_except |
Specifies a _file_ inJSON Web Key Setformat for validating JWT signature. Parameter value can contain variables.
Several auth_jwt_key_file directives can be specified on the same level (1.21.1):
auth_jwt_key_file conf/keys.json; auth_jwt_key_file conf/key.jwk;
If at least one of the specified keys cannot be loaded or processed, nginx will return the 500 (Internal Server Error) error.
| Syntax: | auth_jwt_key_request uri; |
|---|---|
| Default: | — |
| Context: | http, server, location, limit_except |
This directive appeared in version 1.15.6.
Allows retrieving aJSON Web Key Setfile from a subrequest for validating JWT signature and sets the URI where the subrequest will be sent to. Parameter value can contain variables. To avoid validation overhead, it is recommended to cache the key file:
proxy_cache_path /data/nginx/cache levels=1 keys_zone=foo:10m;
server { ...
location / { auth_jwt "closed site"; auth_jwt_key_request /jwks_uri; }
location = /jwks_uri { internal; proxy_cache foo; proxy_pass http://idp.example.com/keys; } }
Several auth_jwt_key_request directives can be specified on the same level (1.21.1):
auth_jwt_key_request /jwks_uri; auth_jwt_key_request /jwks2_uri;
If at least one of the specified keys cannot be loaded or processed, nginx will return the 500 (Internal Server Error) error.
| Syntax: | auth_jwt_leeway time; |
|---|---|
| Default: | auth_jwt_leeway 0s; |
| Context: | http, server, location |
This directive appeared in version 1.13.10.
Sets the maximum allowable leeway to compensate clock skew when verifying theexpandnbfJWT claims.
| Syntax: | auth_jwt_type signed |encrypted | nested; |
|---|---|---|
| Default: | auth_jwt_type signed; | |
| Context: | http, server, location, limit_except |
This directive appeared in version 1.19.7.
Specifies which type of JSON Web Token to expect: JWS (signed), JWE (encrypted), or signed and then encrypted Nested JWT (nested) (1.21.0).
| Syntax: | auth_jwt_require $value ... [error=401 |403] ; |
|---|---|
| Default: | — |
| Context: | http, server, location, limit_except |
This directive appeared in version 1.21.2.
Specifies additional checks for JWT validation. The value can contain text, variables, and their combination, and must start with a variable (1.21.7). The authentication will succeed only if all the values are not empty and are not equal to “0”.
map jwtclaimissjwt_claim_iss jwtclaimissvalid_jwt_iss { "good" 1; } ...
auth_jwt_require $valid_jwt_iss;
If any of the checks fails, the 401 error code is returned. The optional error parameter (1.21.7) allows redefining the error code to 403.
Embedded Variables
The ngx_http_auth_jwt_module module supports embedded variables:
returns the value of a specifiedJOSE header
$jwt_claim_ _name_
returns the value of a specifiedJWT claim
For nested claims and claims including a dot (“.”), the value of the variable cannot be evaluated; the auth_jwt_claim_set directive should be used instead.
Variable values for tokens encrypted with JWE are available only after decryption which occurs during theAccess phase.
$jwt_payload
returns the decrypted top-level payload of nestedor encrypted tokens (1.21.2). For nested tokens returns the enclosed JWS token. For encrypted tokens returns JSON with claims.