Module ngx_http_auth_jwt_module

• Supported Algorithms
• Example Configuration
• Directives
• auth_jwt
• auth_jwt_claim_set
• auth_jwt_header_set
• auth_jwt_key_file
• auth_jwt_key_request
• auth_jwt_leeway
• auth_jwt_type
• 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 can be encoded in a JSON Web Signature (JWS) or JSON Web Encryption (JWE) (1.19.7) 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.

This module is available as part of our commercial subscription.

Supported Algorithms

The module supports the following JSON Web Algorithms.

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

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.

Variable values for tokens encrypted with JWE are available only after decryption which occurs during the Access phase.

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

Sets the maximum allowable leeway to compensate clock skew when verifying the exp and nbf JWT claims.

Specifies which type of JSON Web Token to expect: JWS (signed) or JWE (encrypted).

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.

Variable values for tokens encrypted with JWE are available only after decryption which occurs during the Access phase.