teslagov-jwt: Asegura tus ubicaciones de NGINX con JWT

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-teslagov-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-teslagov-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-teslagov-jwt v2.4.0 lanzado el 17 de septiembre de 2025.

Este es un módulo de NGINX para verificar un JWT válido y hacer proxy a un servidor ascendente o redirigir a una página de inicio de sesión. Soporta características adicionales como la extracción de claims del JWT y colocarlos en los encabezados de solicitud/respuesta.

Cambios importantes con v2

La rama v2, que ahora ha sido fusionada con master, incluye cambios importantes. Por favor, consulta el lanzamiento inicial de v2 para más detalles.

Directivas

Este módulo requiere varias nuevas directivas de nginx.conf, que pueden ser especificadas a nivel de http, server o location. Consulta el ejemplo de archivo de configuración de NGINX para más información.

Directiva	Descripción
`auth_jwt_key`	La clave a usar para decodificar/verificar el JWT, en formato binhex -- ver más abajo.
`auth_jwt_redirect`	Establecer en "on" para redirigir a `auth_jwt_loginurl` si la autenticación falla.
`auth_jwt_loginurl`	La URL a la que redirigir si `auth_jwt_redirect` está habilitado y la autenticación falla.
`auth_jwt_enabled`	Establecer en "on" para habilitar la verificación de JWT.
`auth_jwt_algorithm`	El algoritmo a usar. Uno de: HS256, HS384, HS512, RS256, RS384, RS512
`auth_jwt_location`	Indica dónde se encuentra el JWT en la solicitud -- ver más abajo.
`auth_jwt_validate_sub`	Establecer en "on" para validar el claim `sub` (por ejemplo, id de usuario) en el JWT.
`auth_jwt_extract_var_claims`	Establecer en una lista delimitada por espacios de claims a extraer del JWT y hacer disponibles como variables de NGINX. Estas serán accesibles a través de e.g: `$jwt_claim_sub`
`auth_jwt_extract_request_claims`	Establecer en una lista delimitada por espacios de claims a extraer del JWT y establecer como encabezados de solicitud. Estas serán accesibles a través de e.g: `$http_jwt_sub`
`auth_jwt_extract_response_claims`	Establecer en una lista delimitada por espacios de claims a extraer del JWT y establecer como encabezados de respuesta. Estas serán accesibles a través de e.g: `$sent_http_jwt_sub`
`auth_jwt_use_keyfile`	Establecer en "on" para leer la clave desde un archivo en lugar de desde la directiva `auth_jwt_key`.
`auth_jwt_keyfile_path`	Establecer en la ruta desde la cual debe leerse la clave cuando `auth_jwt_use_keyfile` está habilitado.

Algoritmos

El algoritmo por defecto es HS256, para validación de clave simétrica. Al usar uno de los algoritmos HS*, el valor para auth_jwt_key debe especificarse en formato binhex. Se recomienda usar al menos 256 bits de datos (32 pares de caracteres hexadecimales o 64 caracteres en total). Ten en cuenta que usar más de 512 bits no aumentará la seguridad. Para pautas sobre claves, consulta NIST Special Publication 800-107 Recommendation for Applications Using Approved Hash Algorithms, Sección 5.3.2 La clave HMAC.

Para generar una clave de 256 bits (32 pares de caracteres hexadecimales; 64 caracteres en total):

openssl rand -hex 32

Algoritmos adicionales soportados

La configuración también soporta validación de clave pública RSA a través de (por ejemplo) auth_jwt_algorithm RS256. Al usar los algoritmos RS*, el campo auth_jwt_key debe establecerse en tu clave pública O auth_jwt_use_keyfile debe establecerse en on y auth_jwt_keyfile_path debe apuntar a la clave pública en disco. NGINX no se iniciará si auth_jwt_use_keyfile está establecido en on y no se proporciona un archivo de clave.

Al usar un algoritmo RS* con una clave en línea, asegúrate de establecer auth_jwt_key en la clave pública, en lugar de un certificado PEM. Por ejemplo:

auth_jwt_key "-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0aPPpS7ufs0bGbW9+OFQ
RvJwb58fhi2BuHMd7Ys6m8D1jHW/AhDYrYVZtUnA60lxwSJ/ZKreYOQMlNyZfdqA
rhYyyUkedDn8e0WsDvH+ocY0cMcxCCN5jItCwhIbIkTO6WEGrDgWTY57UfWDqbMZ
4lMn42f77OKFoxsOA6CVvpsvrprBPIRPa25H2bJHODHEtDr/H519Y681/eCyeQE/
1ibKL2cMN49O7nRAAaUNoFcO89Uc+GKofcad1TTwtTIwmSMbCLVkzGeExBCrBTQo
wO6AxLijfWV/JnVxNMUiobiKGc/PP6T5PI70Uv67Y4FzzWTuhqmREb3/BlcbPwtM
oQIDAQAB
-----END PUBLIC KEY-----";

Al usar un algoritmo RS* con un archivo de clave pública, haz lo siguiente:

auth_jwt_use_keyfile on;
auth_jwt_keyfile_path "/path/to/pub_key.pem";

Un caso de uso típico sería especificar la clave y la URL de inicio de sesión a nivel de http, y luego solo activar la autenticación JWT para las ubicaciones que deseas asegurar (o viceversa). Las solicitudes no autorizadas resultarán en una respuesta 302 Moved Temporarily con el encabezado Location establecido en la URL especificada en la directiva auth_jwt_loginurl, y un parámetro de cadena de consulta return_url cuyo valor es la URL actual/intentada.

Si prefieres devolver 401 Unauthorized en lugar de redirigir, puedes desactivar auth_jwt_redirect:

auth_jwt_redirect off;

Ubicaciones JWT

Por defecto, se utiliza el encabezado Authorization para proporcionar un JWT para la validación. Sin embargo, puedes usar la directiva auth_jwt_location para especificar el nombre del encabezado o cookie que proporciona el JWT:

auth_jwt_location HEADER=auth-token;  # obtener el JWT del encabezado "auth-token"
auth_jwt_location COOKIE=auth-token;  # obtener el JWT de la cookie "auth-token"

Validación de `sub`

Opcionalmente, el módulo puede validar que un claim sub (por ejemplo, el id del usuario) exista en el JWT. Puedes habilitar esta característica de la siguiente manera:

auth_jwt_validate_sub on;

Extracción de Claims del JWT

Puedes especificar claims a extraer del JWT y colocarlos en los encabezados de solicitud y/o respuesta. Esto es especialmente útil porque los claims estarán disponibles como variables de NGINX.

Si solo deseas acceder a un claim como una variable de NGINX, debes usar auth_jwt_extract_var_claims para que el claim no termine siendo enviado al cliente como un encabezado de respuesta. Sin embargo, si deseas que el claim sea enviado al cliente en la respuesta, puedes usar auth_jwt_extract_response_claims en su lugar.

Ten en cuenta que los claims de tipo number, boolean, array y object no son soportados en este momento -- solo se soportan claims de tipo string. Se lanzará un error si intentas extraer un claim que no sea de tipo string.

Usando Claims

Por ejemplo, podrías configurar una ubicación de NGINX que redirija al perfil del usuario actual. Supongamos que sub=abc-123, la configuración a continuación redirigiría a /profile/abc-123.

location /profile/me {
    auth_jwt_extract_var_claims sub;

    return 301 /profile/$jwt_claim_sub;
}

Usando Claims de Respuesta

Los claims de respuesta se utilizan de la misma manera, con las únicas diferencias siendo: - las variables se acceden a través del patrón $sent_http_jwt_*, por ejemplo, $sent_http_jwt_sub, y - los encabezados se envían al cliente.

Extracción de Múltiples Claims

Puedes extraer múltiples claims especificando todos los claims como argumentos a una sola directiva, o suministrando múltiples directivas. Los siguientes dos ejemplos son equivalentes.

auth_jwt_extract_request_claims sub firstName lastName;

auth_jwt_extract_request_claims sub;
auth_jwt_extract_request_claims firstName;
auth_jwt_extract_request_claims lastName;

Clonando `libjwt`

Clona este repositorio de la siguiente manera (reemplaza <target_dir>): git clone [email protected]:benmcollins/libjwt.git <target_dir>
Entra en el directorio y cambia a la última etiqueta: git checkout $(git tag | sort -Vr | head -n 1)
Actualiza las entradas de includePath mostradas arriba para que coincidan con la ubicación que elegiste.

Clonando `libjansson`

Clona este repositorio de la siguiente manera (reemplaza <target_dir>): git clone [email protected]:akheron/jansson.git <target_dir>
Entra en el directorio y cambia a la última etiqueta: git checkout $(git tag | sort -Vr | head -n 1)
Actualiza las entradas de includePath mostradas arriba para que coincidan con la ubicación que elegiste.

Verificando la Compilación

Una vez que guardes tus cambios en .vscode/c_cpp_properties.json, deberías ver que las advertencias y errores en el panel de Problemas desaparecen, al menos temporalmente. Esperemos que no regresen, pero si lo hacen, asegúrate de que tus rutas de inclusión estén configuradas correctamente.

Para sistemas Linux con systemd (opcional)

export LOG_DRIVER=journald

Para otros sistemas o si prefieres registros basados en archivos (por defecto)

export LOG_DRIVER=json-file

reconstruir las imágenes de prueba

./scripts rebuild_test

ejecutar las pruebas

./scripts test

verificar los registros -- ajusta el nombre del contenedor según sea necesario

Para journald (sistemas Linux):

journalctl -eu docker CONTAINER_NAME=nginx-auth-jwt-test-nginx

Para el controlador json-file (todos los sistemas):

docker logs nginx-auth-jwt-test-nginx

Ahora podrás ver los registros de ejecuciones de prueba anteriores. La mejor manera de hacer uso de esto es abrir dos terminales, una donde ejecutes las pruebas, y otra donde sigas los registros:

```shell
## terminal 1
./scripts test

## terminal 2 - elige según tu configuración de LOG_DRIVER:

## Para journald:
journalctl -fu docker CONTAINER_NAME=jwt-nginx-test

## Para json-file (por defecto):
docker logs -f nginx-auth-jwt-test-nginx

GitHub

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