jwt: Módulo JWT de NGINX

Instalación

Puedes instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero no limitado a:

RedHat Enterprise Linux 7, 8, 9 y 10
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 y Amazon Linux 2023

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 y Amazon Linux 2

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

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-jwt

Habilita el módulo añadiendo lo siguiente en la parte superior de /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_jwt_module.so;

Este documento describe nginx-module-jwt v3.4.4 lanzado el 03 de febrero de 2026.

Módulo de autenticación jwt de Nginx

Este es un módulo de NGINX para verificar un JWT válido, este módulo tiene la intención de ser lo más ligero posible y de permanecer simple:

Imagen de Docker basada en el Dockerfile oficial de nginx (alpine).
Imagen ligera (~400KB más que la oficial).

Inicio Rápido:

Imagen de Docker:

La imagen se genera con Github Actions (ver nginx-jwt-module:latest)

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

Paquetes preconstruidos (Ubuntu / Debian)

Los paquetes preconstruidos para este módulo están disponibles de forma gratuita desde el repositorio de GetPageSpeed:

# Agrega el repositorio (ejemplo de Ubuntu - reemplaza 'ubuntu' y 'jammy' por tu distro)
echo "deb [signed-by=/etc/apt/keyrings/getpagespeed.gpg] https://extras.getpagespeed.com/ubuntu jammy main" \
  | sudo tee /etc/apt/sources.list.d/getpagespeed-extras.list

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

http {
    server {
        auth_jwt_key "0123456789abcdef" hex; # Tu clave como cadena hex
        auth_jwt     off;

        # El método de autenticación predeterminado es el encabezado "Authentication"
        location /secured-by-auth-header/ {
            auth_jwt on;
        }

        # Pero puedes usar una cookie en su lugar
        location /secured-by-cookie/ {
            auth_jwt $cookie_MyCookieName;
        }

        # Las claves JWT se heredan del nivel de configuración anterior
        # pero puedes tener diferentes claves para diferentes ubicaciones
        location /secured-by-auth-header-too/ {
            auth_jwt_key "another-secret"; # Tu clave como cadena utf8
            auth_jwt on;
        }

        location /secured-by-rsa-key/ {
            auth_jwt_key /etc/keys/rsa-public.pem file; # Tu clave desde un archivo PEM
            auth_jwt on;
        }

        location /not-secure/ {}
    }
}

Nota: no olvides cargar el módulo en el contexto principal:

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

Directivas:

auth_jwt

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

Habilita la validación de JWT.

El valor auth_jwt $variable se puede usar para establecer una forma personalizada de obtener el JWT, por ejemplo, para obtenerlo de una cookie en lugar del encabezado Authentication predeterminado: auth_jwt $cookie_MyCookieName;

auth_jwt_key

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

Especifica la clave para validar la firma del JWT (debe ser hexadecimal).
La opción encoding puede ser hex | utf8 | base64 | file (el valor predeterminado es utf8).
La opción file requiere que el value sea una ruta de archivo válida (apuntando a una clave codificada en PEM).

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

Especifica qué algoritmo el servidor espera recibir en el JWT.

auth_jwt_require

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

Especifica verificaciones adicionales para la validación del JWT. La autenticación solo tendrá éxito si todos los valores no están vacíos y no son iguales a “0”.

Estas directivas se heredan del nivel de configuración anterior si y solo si no hay directivas auth_jwt_require definidas en el nivel actual.

Si alguna de las verificaciones falla, se devuelve el código de error 401. El parámetro de error opcional permite redefinir el código de error a 403.

Ejemplo:

# 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;
    # ...
  }
}

Ten en cuenta que como $jwt_claim_ devuelve un valor codificado en JSON, debemos verificar \"value\" (y no value)

Variables Embebidas:

El módulo ngx_http_auth_jwt_module soporta variables embebidas:

$jwtheadername devuelve el valor del encabezado especificado
$jwtclaimname devuelve el valor del reclamo especificado
$jwt_headers devuelve encabezados
$jwt_payload devuelve carga útil

Ten en cuenta que como todos los valores devueltos están codificados en JSON, las cadenas estarán rodeadas por el carácter "

Extiende Tu Imagen de Docker:

Simplemente crea tu imagen a partir de la generada por Github

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

# Copia tu configuración de nginx
# No olvides incluir este módulo en tu configuración
# 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;"]

O usa la proporcionada directamente

docker run -p 80:80 \
  -v ./nginx.conf:/etc/nginx/nginx.conf \
  ghcr.io/max-lt/nginx-jwt-module

o

docker build -f Dockerfile -t jwt-nginx .

### Prueba:

#### Uso predeterminado:

```bash
make test # Construirá una imagen de prueba y ejecutará la suite de pruebas

Ejemplos de configuraciones:

En esta sección, veremos algunos ejemplos de cómo usar este módulo.

Redirigir a la página de inicio de sesión si el JWT es inválido:

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

# ...

http {
    server {
        listen 80;
        server_name _;

        auth_jwt_key "0123456789abcdef" hex; # Tu clave como cadena hex
        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";
        }
    }
}

Intentar curl -i http://localhost/secure/path?param=value devolverá una redirección 302 a /login?redirect=/secure/path?param=value si el JWT es inválido.

GitHub

Puedes encontrar consejos adicionales de configuración y documentación para este módulo en el repositorio de GitHub para nginx-module-jwt.