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
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 notvalue
)
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.