Skip to content
NGINX module to check for a valid JWT.
Branch: master
Clone or download
Pull request Compare This branch is 12 commits ahead of max-lt:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
test-image
.dockerignore
.editorconfig
.gitignore
CONTRIBUTING.md
Dockerfile
LICENSE
Makefile
README.md
build
config
test

README.md

Nginx jwt auth module

Build Status Build Status Docker pulls

This is an NGINX module to check for a valid JWT.

Inspired by TeslaGov, ch1bo and tizpuppi, this module intend to be as light as possible and to remain simple.

Module:

Example Configuration:

server {
    auth_jwt_key "0123456789abcdef" hex; # Your key as hex string
    auth_jwt     off;

    location /secured-by-cookie/ {
        auth_jwt $cookie_MyCookieName;
    }

    location /secured-by-auth-header/ {
        auth_jwt on;
    }

    location /secured-by-auth-header-too/ {
        auth_jwt_key "another-secret"; # Your key as utf8 string
        auth_jwt on;
    }

    location /secured-by-rsa-key/ {
        auth_jwt_key /etc/keys/rsa-public.pem file; # Your key from a PEM file
        auth_jwt on;
    }

    location /not-secure/ {}
}

Note: don't forget to load the module in the main context:
load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;

Directives:

Syntax:	 auth_jwt $variable | on | off;
Default: auth_jwt off;
Context: http, server, location

Enables validation of JWT.


Syntax:	 auth_jwt_key value [encoding];
Default: ——
Context: http, server, location

Specifies the key for validating JWT signature (must be hexadecimal).
The encoding otpion may be hex | utf8 | base64 | file (default is utf8).
The file option requires the value to be a valid file path (pointing to a PEM encoded key).


Syntax:	 auth_jwt_alg any | HS256 | HS384 | HS512 | RS256 | RS384 | RS512 | ES256 | ES384 | ES512;
Default: auth_jwt_alg any;
Context: http, server, location

Specifies which algorithm the server expects to receive in the JWT.

Following need jwt_get_grants & jwt_get_headers

Syntax:	 auth_jwt_header_set $variable name ...;
Default: ——
Context: http, server, location

Sets the variable to a JOSE header parameter identified by key names.
Name matching starts from the top level of the JSON tree.

Syntax:	 auth_jwt_grant_set $variable name ...;
Default: ——
Context: http, server, location

Sets the variable to a JWT grant parameter identified by key names.
Name matching starts from the top level of the JSON tree.

Embedded Variables:

Module supports embedded variables:

$jwt_header

returns whole header

$jwt_grant

returns whole grant

$jwt_header_name

returns header.name

$jwt_grant_name

returns grant.name

Build:

This module is built inside a docker container, from the nginx-alpine image.

./build # Will create a "jwt-nginx" (Dockerfile)

Test:

Default usage:

./test # Will create a "jwt-nginx-test" image (from test-image/Dockerfile) based on the "jwt-nginx" one.

Set image name:

./test your-image-to-test

example:

./test jwt-nginx-s1 # tests the development image

Use current container:

./test --current my-container

example:

# In a first terminal:
docker run --rm --name my-test-container -p 8000:8000 jwt-nginx-test

# In a second one:
./test --current my-test-container
You can’t perform that action at this time.