jwt: Módulo JWT do NGINX

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

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-jwt v3.4.4 lançado em 03 de fevereiro de 2026.

Módulo de autenticação jwt do Nginx

Este é um módulo NGINX para verificar um JWT válido, este módulo pretende ser o mais leve possível e permanecer simples:

Imagem Docker baseada no Dockerfile oficial do nginx (alpine).
Imagem leve (~400KB a mais que a oficial).

Início Rápido:

Imagem Docker:

A imagem é gerada com GitHub Actions (veja nginx-jwt-module:latest)

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

Pacotes pré-compilados (Ubuntu / Debian)

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

# Adicione o repositório (exemplo para Ubuntu - substitua 'ubuntu' e 'jammy' pela sua distribuição)
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; # Sua chave como string hexadecimal
        auth_jwt     off;

        # O método de autenticação padrão é o cabeçalho "Authentication"
        location /secured-by-auth-header/ {
            auth_jwt on;
        }

        # Mas você pode usar um cookie em vez disso
        location /secured-by-cookie/ {
            auth_jwt $cookie_MyCookieName;
        }

        # As chaves JWT são herdadas do nível de configuração anterior
        # mas você pode ter chaves diferentes para diferentes locais
        location /secured-by-auth-header-too/ {
            auth_jwt_key "another-secret"; # Sua chave como string utf8
            auth_jwt on;
        }

        location /secured-by-rsa-key/ {
            auth_jwt_key /etc/keys/rsa-public.pem file; # Sua chave de um arquivo PEM
            auth_jwt on;
        }

        location /not-secure/ {}
    }
}

Nota: não se esqueça de carregar o módulo no contexto principal:

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

Diretivas:

auth_jwt

Sintaxe:     auth_jwt $variável | on | off;
Padrão: auth_jwt off;
Contexto: http, server, location

Habilita a validação do JWT.

O valor auth_jwt $variável pode ser usado para definir uma maneira personalizada de obter o JWT, por exemplo, para obtê-lo de um cookie em vez do cabeçalho Authentication padrão: auth_jwt $cookie_MyCookieName;

auth_jwt_key

Sintaxe:     auth_jwt_key valor [codificação];
Padrão: ——
Contexto: http, server, location

Especifica a chave para validar a assinatura do JWT (deve ser hexadecimal).
A opção codificação pode ser hex | utf8 | base64 | file (o padrão é utf8).
A opção file requer que o valor seja um caminho de arquivo válido (apontando para uma chave codificada em PEM).

auth_jwt_alg

Sintaxe:     auth_jwt_alg any | HS256 | HS384 | HS512 | RS256 | RS384 | RS512 | ES256 | ES384 | ES512;
Padrão: auth_jwt_alg any;
Contexto: http, server, location

Especifica qual algoritmo o servidor espera receber no JWT.

auth_jwt_require

Sintaxe:     auth_jwt_require $valor ... [error=401 | 403];
Padrão: ——
Contexto: http, server, location

Especifica verificações adicionais para a validação do JWT. A autenticação só terá sucesso se todos os valores não estiverem vazios e não forem iguais a “0”.

Essas diretivas são herdadas do nível de configuração anterior se e somente se não houver diretivas auth_jwt_require definidas no nível atual.

Se alguma das verificações falhar, o código de erro 401 é retornado. O parâmetro de erro opcional permite redefinir o código de erro para 403.

Exemplo:

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

Note que como $jwt_claim_ retorna um valor codificado em JSON, então precisamos verificar \"value\" (e não value)

Variáveis Embutidas:

O módulo ngx_http_auth_jwt_module suporta variáveis embutidas:

$jwtheadername retorna o valor do cabeçalho especificado
$jwtclaimname retorna o valor da reivindicação especificada
$jwt_headers retorna cabeçalhos
$jwt_payload retorna payload

Note que como todos os valores retornados são codificados em JSON, as strings estarão cercadas pelo caractere "

Estenda Sua Imagem Docker:

Simplesmente crie sua imagem a partir da gerada pelo GitHub

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

# Copie sua configuração do nginx
# Não se esqueça de incluir este módulo na sua configuração
# 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;"]

Ou use a fornecida diretamente

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

ou

docker build -f Dockerfile -t jwt-nginx .

### Teste:

#### Uso padrão:

```bash
make test # Irá construir uma imagem de teste e executar a suíte de testes

Exemplos de configurações:

Nesta seção, veremos alguns exemplos de como usar este módulo.

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

# ...

http {
    server {
        listen 80;
        server_name _;

        auth_jwt_key "0123456789abcdef" hex; # Sua chave como string 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";
        }
    }
}

Tentando curl -i http://localhost/secure/path?param=value retornará um redirecionamento 302 para /login?redirect=/secure/path?param=value se o JWT for inválido.

GitHub

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