Saltar a contenido

jwt: Módulo JWT para NGINX

Instalación

Puede instalar este módulo en cualquier distribución basada en RHEL, incluyendo, pero sin limitarse 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
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

Habilite el módulo añadiendo lo siguiente al principio de /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_jwt_module.so;

Este documento describe nginx-module-jwt v3.4.6 publicado el 01 de agosto de 2026.

Módulo de autenticación JWT para Nginx

License

Este es un módulo de NGINX para verificar un JWT válido. Este módulo pretende ser lo más ligero posible y mantener la simplicidad:

Inicio rápido:

Imagen Docker:

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

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

También está disponible una variante más ligera basada en nginx:alpine-slim (sin los módulos dinámicos adicionales de nginx como njs, image-filter, xslt o geoip):

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

Paquetes precompilados (Ubuntu / Debian)

Los paquetes precompilados para este módulo están disponibles gratuitamente en el repositorio de GetPageSpeed:

# Añadir el repositorio (ejemplo para Ubuntu - reemplace 'ubuntu' y 'jammy' según su distribución)
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; # Su clave como cadena hexadecimal
        auth_jwt     off;

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

        # Pero puede 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 puede tener diferentes claves para diferentes ubicaciones
        location /secured-by-auth-header-too/ {
            auth_jwt_key "another-secret"; # Su clave como cadena utf8
            auth_jwt on;
        }

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

        location /not-secure/ {}
    }
}

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

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

Directivas:

auth_jwt

Sintaxis:    auth_jwt $variable | on | off;
Predeterminado: auth_jwt off;
Contexto: 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

Sintaxis:    auth_jwt_key valor [codificación];
Predeterminado: ——
Contexto: http, server, location

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

auth_jwt_alg

Sintaxis:    auth_jwt_alg any | HS256 | HS384 | HS512 | RS256 | RS384 | RS512 | ES256 | ES384 | ES512;
Predeterminado: auth_jwt_alg any;
Contexto: http, server, location

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

Los tokens firmados con un algoritmo HMAC (HS256, HS384, HS512) siempre se rechazan cuando la clave es una clave PEM, independientemente de lo que establezca esta directiva: una clave pública no es un secreto, por lo que cualquiera podría usarla para firmar un token que el servidor aceptaría. Se recomienda fijar el algoritmo esperado.

auth_jwt_require

Sintaxis:    auth_jwt_require $valor ... [error=401 | 403];
Predeterminado: ——
Contexto: http, server, location

Especifica comprobaciones adicionales para la validación de 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 comprobaciones falla, se devuelve el código de error 401. El parámetro opcional error 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;
    # ...
  }
}

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

Variables integradas:

El módulo ngx_http_auth_jwt_module admite variables integradas:

  • $jwtheadernombre devuelve el valor del encabezado especificado
  • $jwtclaimnombre devuelve el valor del claim especificado
  • $jwt_headers devuelve los encabezados
  • $jwt_payload devuelve el payload

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

Amplíe su imagen Docker:

Simplemente cree su imagen a partir de la generada por Github

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

# Copie su configuración de nginx
# No olvide incluir este módulo en su 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 use 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 . 

### Pruebas:

#### Uso predeterminado:

```bash
make test # Creará una imagen de prueba y ejecutará el conjunto de pruebas

Ejemplos de configuración:

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 no es válido:

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

# ...

http {
    server {
        listen 80;
        server_name _;

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

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

GitHub

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