teslagov-jwt: Proteja suas localizações NGINX com JWT

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

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

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023+CentOS/RHEL 7 e 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

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_jwt_module.so;

Este documento descreve o nginx-module-teslagov-jwt v2.4.0 lançado em 17 de setembro de 2025.

Este é um módulo NGINX para verificar um JWT válido e fazer proxy para um servidor upstream ou redirecionar para uma página de login. Ele suporta recursos adicionais, como a extração de claims do JWT e sua colocação nos cabeçalhos de requisição/resposta.

Mudanças Quebradas com v2

O branch v2, que agora foi mesclado ao master, inclui mudanças quebradas. Consulte o lançamento inicial do v2 para mais detalhes.

Diretrizes

Este módulo requer várias novas diretrizes nginx.conf, que podem ser especificadas nos níveis http, server ou location. Consulte o exemplo de arquivo de configuração NGINX para mais informações.

Diretriz	Descrição
`auth_jwt_key`	A chave a ser usada para decodificar/verificar o JWT, em formato binhex -- veja abaixo.
`auth_jwt_redirect`	Defina como "on" para redirecionar para `auth_jwt_loginurl` se a autenticação falhar.
`auth_jwt_loginurl`	A URL para redirecionar se `auth_jwt_redirect` estiver habilitado e a autenticação falhar.
`auth_jwt_enabled`	Defina como "on" para habilitar a verificação do JWT.
`auth_jwt_algorithm`	O algoritmo a ser usado. Um dos: HS256, HS384, HS512, RS256, RS384, RS512
`auth_jwt_location`	Indica onde o JWT está localizado na requisição -- veja abaixo.
`auth_jwt_validate_sub`	Defina como "on" para validar a claim `sub` (por exemplo, id do usuário) no JWT.
`auth_jwt_extract_var_claims`	Defina como uma lista delimitada por espaços de claims a serem extraídas do JWT e disponibilizadas como variáveis NGINX. Estas estarão acessíveis via e.g: `$jwt_claim_sub`
`auth_jwt_extract_request_claims`	Defina como uma lista delimitada por espaços de claims a serem extraídas do JWT e definidas como cabeçalhos de requisição. Estas estarão acessíveis via e.g: `$http_jwt_sub`
`auth_jwt_extract_response_claims`	Defina como uma lista delimitada por espaços de claims a serem extraídas do JWT e definidas como cabeçalhos de resposta. Estas estarão acessíveis via e.g: `$sent_http_jwt_sub`
`auth_jwt_use_keyfile`	Defina como "on" para ler a chave de um arquivo em vez de da diretiva `auth_jwt_key`.
`auth_jwt_keyfile_path`	Defina o caminho de onde a chave deve ser lida quando `auth_jwt_use_keyfile` estiver habilitado.

Algoritmos

O algoritmo padrão é HS256, para validação de chave simétrica. Ao usar um dos algoritmos HS*, o valor para auth_jwt_key deve ser especificado em formato binhex. Recomenda-se usar pelo menos 256 bits de dados (32 pares de caracteres hexadecimais ou 64 caracteres no total). Observe que usar mais de 512 bits não aumentará a segurança. Para diretrizes de chave, consulte NIST Special Publication 800-107 Recommendation for Applications Using Approved Hash Algorithms, Seção 5.3.2 A Chave HMAC.

Para gerar uma chave de 256 bits (32 pares de caracteres hexadecimais; 64 caracteres no total):

openssl rand -hex 32

Algoritmos Adicionais Suportados

A configuração também suporta validação de chave pública RSA via (por exemplo) auth_jwt_algorithm RS256. Ao usar os algoritmos RS*, o campo auth_jwt_key deve ser definido como sua chave pública OU auth_jwt_use_keyfile deve ser definido como on e auth_jwt_keyfile_path deve apontar para a chave pública no disco. O NGINX não iniciará se auth_jwt_use_keyfile estiver definido como on e um arquivo de chave não for fornecido.

Ao usar um algoritmo RS* com uma chave inline, certifique-se de definir auth_jwt_key como a chave pública, em vez de um certificado PEM. Por exemplo:

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-----";

Ao usar um algoritmo RS* com um arquivo de chave pública, faça o seguinte:

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

Um caso de uso típico seria especificar a chave e a URL de login no nível http, e então apenas ativar a autenticação JWT para as localizações que você deseja proteger (ou vice-versa). Requisições não autorizadas resultarão em uma resposta 302 Moved Temporarily com o cabeçalho Location definido para a URL especificada na diretiva auth_jwt_loginurl, e um parâmetro de querystring return_url cujo valor é a URL atual / tentada.

Se você preferir retornar 401 Unauthorized em vez de redirecionar, pode desativar auth_jwt_redirect:

auth_jwt_redirect off;

Localizações JWT

Por padrão, o cabeçalho Authorization é usado para fornecer um JWT para validação. No entanto, você pode usar a diretiva auth_jwt_location para especificar o nome do cabeçalho ou cookie que fornece o JWT:

auth_jwt_location HEADER=auth-token;  # obter o JWT do cabeçalho "auth-token"
auth_jwt_location COOKIE=auth-token;  # obter o JWT do cookie "auth-token"

Validação de `sub`

Opcionalmente, o módulo pode validar se uma claim sub (por exemplo, o id do usuário) existe no JWT. Você pode habilitar esse recurso da seguinte forma:

auth_jwt_validate_sub on;

Extraindo Claims do JWT

Você pode especificar claims a serem extraídas do JWT e colocadas nos cabeçalhos de requisição e/ou resposta. Isso é especialmente útil porque as claims estarão então também disponíveis como variáveis NGINX.

Se você deseja acessar uma claim apenas como uma variável NGINX, deve usar auth_jwt_extract_var_claims para que a claim não acabe sendo enviada ao cliente como um cabeçalho de resposta. No entanto, se você deseja que a claim seja enviada ao cliente na resposta, pode usar auth_jwt_extract_response_claims em vez disso.

Por favor, note que claims do tipo number, boolean, array e object não são suportadas neste momento -- apenas claims do tipo string são suportadas. Um erro será gerado se você tentar extrair uma claim que não seja do tipo string.

Usando Claims

Por exemplo, você poderia configurar uma localização NGINX que redireciona para o perfil do usuário atual. Suponha que sub=abc-123, a configuração abaixo redirecionaria para /profile/abc-123.

location /profile/me {
    auth_jwt_extract_var_claims sub;

    return 301 /profile/$jwt_claim_sub;
}

Usando Claims de Resposta

Claims de resposta são usadas da mesma forma, com as únicas diferenças sendo: - as variáveis são acessadas via o padrão $sent_http_jwt_*, por exemplo, $sent_http_jwt_sub, e - os cabeçalhos são enviados ao cliente.

Extraindo Múltiplas Claims

Você pode extrair múltiplas claims especificando todas as claims como argumentos para uma única diretiva, ou fornecendo múltiplas diretivas. Os dois exemplos a seguir são 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`

Clone este repositório da seguinte forma (substitua <target_dir>): git clone [email protected]:benmcollins/libjwt.git <target_dir>
Entre no diretório e mude para a última tag: git checkout $(git tag | sort -Vr | head -n 1)
Atualize as entradas includePath mostradas acima para corresponder ao local que você escolheu.

Clonando `libjansson`

Clone este repositório da seguinte forma (substitua <target_dir>): git clone [email protected]:akheron/jansson.git <target_dir>
Entre no diretório e mude para a última tag: git checkout $(git tag | sort -Vr | head -n 1)
Atualize as entradas includePath mostradas acima para corresponder ao local que você escolheu.

Verificando a Compilação

Uma vez que você salve suas alterações em .vscode/c_cpp_properties.json, você deve ver que avisos e erros no painel de Problemas desaparecem, pelo menos temporariamente. Esperamos que eles não voltem, mas se voltarem, certifique-se de que seus caminhos de inclusão estão configurados corretamente.

Para sistemas Linux com systemd (opcional)

export LOG_DRIVER=journald

Para outros sistemas ou se você preferir logs baseados em arquivos (padrão)

export LOG_DRIVER=json-file

reconstrua as imagens de teste

./scripts rebuild_test

execute os testes

./scripts test

verifique os logs -- ajuste o nome do contêiner conforme necessário

Para journald (sistemas Linux):

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

Para driver json-file (todos os sistemas):

docker logs nginx-auth-jwt-test-nginx

Agora você poderá ver logs de execuções de teste anteriores. A melhor maneira de aproveitar isso é abrir dois terminais, um onde você executa os testes e um onde você acompanha os logs:

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

## terminal 2 - escolha com base na sua configuração de LOG_DRIVER:

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

## Para json-file (padrão):
docker logs -f nginx-auth-jwt-test-nginx

GitHub

Você pode encontrar dicas de configuração adicionais e documentação para este módulo no repositório GitHub do nginx-module-teslagov-jwt.