nginx / current / reference / http-ngx_http_auth_jwt_module.html

Module ngx_http_auth_jwt_module

The ngx_http_auth_jwt_module module (1.11.3) implements client authorization by validating the provided JSON Web Token (JWT) using the specified keys. JWT claims must be encoded in a JSON Web Signature (JWS) structure. The module can be used for OpenID Connect authentication.

The module may be combined with other access modules, such as ngx_http_access_module, ngx_http_auth_basic_module, and ngx_http_auth_request_module, via the satisfy directive.

The module supports the following cryptographic 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.

This module is available as part of our commercial subscription .

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 a Bearer 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.

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_file file;
Default:
Context: http, server, location, limit_except

Specifies a file in JSON Web Key Set format for validating JWT signature. Parameter value can contain variables.

Syntax: auth_jwt_key_request uri;
Default:
Context: http, server, location, limit_except

This directive appeared in version 1.15.6.

Allows retrieving a JSON Web Key Set file from a subrequest for validating JWT signature and sets the URI where the subrequest will be sent to. 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;
    }
}

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 the exp and nbf JWT claims.

Embedded Variables

The ngx_http_auth_jwt_module module supports embedded variables:

$jwt_header_ name
returns the value of a specified JOSE header
$jwt_claim_ name
returns the value of a specified JWT 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.