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.5.0 lançado em 11 de junho de 2026.

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 a colocação deles 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. Veja 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 o claim `sub` (por exemplo, id do usuário) no JWT.
`auth_jwt_extract_var_claims`	Defina como uma lista de claims delimitadas por espaço para extrair do JWT e torná-las disponíveis como variáveis NGINX. Essas serão acessíveis via, por exemplo: `$jwt_claim_sub`
`auth_jwt_extract_request_claims`	Defina como uma lista de claims delimitadas por espaço para extrair do JWT e definir como cabeçalhos de requisição. Essas serão acessíveis via, por exemplo: `$http_jwt_sub`
`auth_jwt_extract_response_claims`	Defina como uma lista de claims delimitadas por espaço para extrair do JWT e definir como cabeçalhos de resposta. Essas serão acessíveis via, por exemplo: `$sent_http_jwt_sub`
`auth_jwt_use_keyfile`	Defina como "on" para ler a chave de um arquivo em vez de usar a diretiva `auth_jwt_key`.
`auth_jwt_keyfile_path`	Defina como 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. É recomendado 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 Suportados Adicionais

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 um 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 os claims estarão disponíveis como variáveis NGINX.

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

Por favor, note que claims number, boolean, array e object não são suportados neste momento -- apenas claims string são suportados. Um erro será lançado se você tentar extrair um claim que não seja uma 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 usados 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últiplos Claims

Você pode extrair múltiplos claims especificando todos os 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;

Pacotes Pré-construídos (Ubuntu / Debian)

Pacotes pré-construídos para este módulo estão disponíveis gratuitamente no repositório GetPageSpeed:

# Adicione o repositório (exemplo Ubuntu - substitua 'ubuntu' e 'jammy' pela sua 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

#### Clonando `libjwt`

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

#### Clonando `libjansson`

1. Clone este repositório da seguinte forma (substitua `<target_dir>`): `git clone [email protected]:akheron/jansson.git <target_dir>`
2. Entre no diretório e mude para a última tag: `git checkout $(git tag | sort -Vr | head -n 1)`
3. 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 os 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:

# terminal 1
./scripts test

# terminal 2 - escolha com base na sua configuração 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 adicionais de configuração e documentação para este módulo no repositório GitHub do nginx-module-teslagov-jwt.