Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/max-lt/nginx-jwt-module
NGINX module to check for a valid JWT.
https://github.com/max-lt/nginx-jwt-module
alpine jwt light nginx nginx-jwt nginx-module nginx-proxy
Last synced: about 6 hours ago
JSON representation
NGINX module to check for a valid JWT.
- Host: GitHub
- URL: https://github.com/max-lt/nginx-jwt-module
- Owner: max-lt
- License: mit
- Created: 2018-06-15T20:34:55.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-06-25T11:38:54.000Z (5 months ago)
- Last Synced: 2024-06-25T13:03:33.229Z (5 months ago)
- Topics: alpine, jwt, light, nginx, nginx-jwt, nginx-module, nginx-proxy
- Language: C
- Size: 93.8 KB
- Stars: 90
- Watchers: 4
- Forks: 37
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-technostructure - max-lt/nginx-jwt-module - lt/nginx-jwt-module: NGINX module to check for a valid JWT. ([🎛️ yunohost](https://github.com/stars/ketsapiwiq/lists/yunohost))
- awesome-technostructure - max-lt/nginx-jwt-module - lt/nginx-jwt-module: NGINX module to check for a valid JWT. ([🎛️ yunohost](https://github.com/stars/ketsapiwiq/lists/yunohost))
README
[github-license-url]: /blob/master/LICENSE
[action-docker-url]: https://github.com/max-lt/nginx-jwt-module/actions/workflows/docker.yml
[github-container-url]: https://github.com/max-lt/nginx-jwt-module/pkgs/container/nginx-jwt-module
# Nginx jwt auth module
[][github-license-url]
[][action-docker-url]
[][action-docker-url]
This is an NGINX module to check for a valid JWT, this module intend to be as light as possible and to remain simple:
- Docker image based on the [official nginx Dockerfile](https://github.com/nginxinc/docker-nginx) (alpine).
- Light image (~400KB more than the official one).
### Table of Contents:
- [Module configuration](#module-configuration)
- [Directives](#directives)
- [Embedded variables](#embedded-variables)
- [Image](#image)
- [Example configurations](#example-configurations)
### Module Configuration:
#### Example Configuration:
```nginx
# nginx.conf
load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;
http {
server {
auth_jwt_key "0123456789abcdef" hex; # Your key as hex string
auth_jwt off;
# Default auth method is "Authentication" header
location /secured-by-auth-header/ {
auth_jwt on;
}
# But you can use a cookie instead
location /secured-by-cookie/ {
auth_jwt $cookie_MyCookieName;
}
# JWT keys are inherited from the previous configuration level
# but you can have different keys for different locations
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](http://nginx.org/en/docs/ngx_core_module.html#load_module) the module in the main context:
```nginx
load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;
```
### Directives:
#### auth_jwt
Syntax: auth_jwt $variable | on | off;
Default: auth_jwt off;
Context: http, server, location
Enables validation of JWT.
The `auth_jwt $variable` value can be used to set a custom way to get the JWT, for example to get it from a cookie instead of the default `Authentication` header: ` auth_jwt $cookie_MyCookieName;`
#### auth_jwt_key
Syntax: auth_jwt_key value [encoding];
Default: ——
Context: http, server, location
Specifies the key for validating JWT signature (must be hexadecimal).
The *encoding* option 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).
#### auth_jwt_alg
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.
#### auth_jwt_require
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:
```nginx
# 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, so we have to check `\"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][github-container-url])
```
docker pull ghcr.io/max-lt/nginx-jwt-module:latest
```
#### Simply create your image from Github's generated one
```dockerfile
FROM ghcr.io/max-lt/nginx-jwt-module:latest
# Copy your 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 use the provided one directly
```bash
docker run -p 80:80 \
-v ./nginx.conf:/etc/nginx/nginx.conf \
ghcr.io/max-lt/nginx-jwt-module
```
### Build:
This module is built inside a docker container, from the [nginx](https://hub.docker.com/_/nginx/)-alpine image.
```bash
make build # Will create a "jwt-nginx" image
# or
docker build -f Dockerfile -t jwt-nginx .
```
### Test:
#### Default usage:
```bash
make test # Will build a test image and run the test suite
```
### Example configurations:
In this section, we will see some examples of how to use this module.
#### Redirect to login page if JWT is invalid:
```nginx
load_module /usr/lib/nginx/modules/ngx_http_auth_jwt_module.so;
# ...
http {
server {
listen 80;
server_name _;
auth_jwt_key "0123456789abcdef" hex; # Your key as hex string
auth_jwt off;
location @login_err_redirect {
return 302 $scheme://$host:$server_port/login?redirect=$request_uri;
}
location /secure/ {
auth_jwt on;
error_page 401 = @login_err_redirect;
}
location / {
return 200 "OK";
}
}
}
```
Trying `curl -i http://localhost/secure/path?param=value` will return a 302 redirect to `/login?redirect=/secure/path?param=value` if the JWT is invalid.