Skip to content

jwt: NGINX JWT Module

Installation

You can install this module in any RHEL-based distribution, including, but not limited to:

  • RedHat Enterprise Linux 6, 7, 8, 9
  • CentOS 6, 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • 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.2.0 released on Nov 01 2022.

Nginx jwt auth module

License

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:

## nginx.conf
load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;

## server.conf
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.

Syntax:  auth_jwt_require $value ... [error=401 | 403];
Default: ——
Context: http, server, location

Specifies additional checks for JWT validation. The authentication will succeed only if all the values are not empty and are not equal to “0”.

These directives are inherited from the previous configuration level if and only if there are no auth_jwt_require directives defined on the current level.

If any of the checks fails, the 401 error code is returned. The optional error parameter allows redefining the error code to 403.

Example: 

## server.conf

map $jwt_claim_role $jwt_has_admin_role {
    \"admin\"  1;
}

map $jwt_claim_scope $jwt_has_restricted_scope {
    \"restricted\"  1;
}

server {
  # ...

  location /auth-require {
    auth_jwt_require $jwt_has_admin_role error=403;
    # ...
  }

  location /auth-compound-require {
    auth_jwt_require $jwt_has_admin_role $jwt_has_restricted_scope error=403;
    # ...
  }
}

Note that as $jwt_claim_ returns a JSON-encoded value, we check form \"value\" (and not value)

Embedded Variables:

The ngx_http_auth_jwt_module module supports embedded variables: - $jwt_header_name returns the specified header value - $jwt_claim_name returns the specified claim value - $jwt_headers returns headers - $jwt_payload returns payload

Note that as all returned values are JSON-encoded, so string will be surrounded by " character

Image:

Image is generated with Github Actions (see nginx-jwt-module:latest)

docker pull ghcr.io/max-lt/nginx-jwt-module:latest

Simply create your image from Github's generated one

FROM ghcr.io/max-lt/nginx-jwt-module:latest

## Copy you nginx conf
## Don't forget to include this module in your configuration
## load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;
COPY my-nginx-conf /etc/nginx

EXPOSE 8000

STOPSIGNAL SIGTERM

CMD ["nginx", "-g", "daemon off;"]

or

docker build -f Dockerfile -t jwt-nginx . 

### Test:

#### Default usage:
```bash
make test # Will build a test image & run test suite

GitHub

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

Back to top