W3cubDocs

/nginx

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

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

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

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

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

© 2002-2017 Igor Sysoev
© 2011-2017 Nginx, Inc.
Licensed under the BSD License.
https://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html