Skip to content

jwt: NGINX JWT Module

Installation

CentOS/RHEL 6, 7, 8 or Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install nginx-module-jwt

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_jwt_module.so;

This document describes nginx-module-jwt v3.0.3 released on Apr 22 2021.


Nginx jwt auth module

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. - Docker image based on the official nginx Dockerfile (alpine). - Light image (~16MB).

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.

Test:

Default usage:

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

Set image name:

./test.sh your-image-to-test
example:
./test.sh jwt-nginx-s1 # tests the development image

Use current container:

./test.sh --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.sh --current my-test-container

GitHub

You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-jwt.

Back to top