Module ngx_http_auth_jwt_module

• Example Configuration
• Directives
• auth_jwt
• auth_jwt_claim_set
• auth_jwt_header_set
• auth_jwt_key_file
• auth_jwt_key_request
• auth_jwt_leeway
• Embedded Variables

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

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.

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.

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.

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

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;
    }
}

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.