Pular para conteúdo

jwt: Módulo JWT para 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
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 o módulo adicionando o seguinte no início do /etc/nginx/nginx.conf:

load_module modules/ngx_http_auth_jwt_module.so;

Este documento descreve o nginx-module-jwt v3.4.6 lançado em 01 de agosto de 2026.

Módulo de autenticação JWT para Nginx

License

Este é um módulo NGINX para verificar se um JWT é válido. Este módulo tem a intenção de ser o mais leve possível e permanecer simples:

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

Uma variante mais leve baseada em nginx:alpine-slim (sem os módulos dinâmicos extras do nginx, como njs, image-filter, xslt ou geoip) também está disponível:

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

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 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
        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 locations
        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 $variable | on | off;
Padrão: auth_jwt off;
Contexto: http, server, location

Habilita a validação de JWT.

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

auth_jwt_key

Sintaxe:     auth_jwt_key value [encoding];
Padrão: ——
Contexto: http, server, location

Especifica a chave para validar a assinatura do JWT (deve ser hexadecimal).
A opção encoding pode ser hex | utf8 | base64 | file (o padrão é utf8).
A opção file requer que o value 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.

Tokens assinados com um algoritmo HMAC (HS256, HS384, HS512) são sempre rejeitados quando a chave é uma chave PEM, independentemente do valor desta diretiva: uma chave pública não é um segredo, então qualquer pessoa poderia usá-la para assinar um token que o servidor aceitaria. Fixar o algoritmo esperado ainda é recomendado.

auth_jwt_require

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

Especifica verificações adicionais para a validação do JWT. A autenticação só será bem-sucedida se todos os valores não estiverem vazios e não forem iguais a "0".

Estas 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 qualquer uma das verificações falhar, o código de erro 401 é retornado. O parâmetro opcional error 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;
    # ...
  }
}

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

Variáveis Incorporadas:

O módulo ngx_http_auth_jwt_module suporta variáveis incorporadas:

  • $jwtheadernome retorna o valor do cabeçalho especificado
  • $jwtclaimnome retorna o valor da claim especificada
  • $jwt_headers retorna os cabeçalhos
  • $jwt_payload retorna o payload

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

Estenda Sua Imagem Docker:

Simplesmente crie sua imagem a partir da imagem 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 imagem 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á compilar uma imagem de teste e executar a suíte de testes

Exemplos de configuração:

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

Redirecionar para a página de login se o JWT for inválido:

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

Tentar 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 de configuração adicionais e documentação para este módulo no repositório GitHub do nginx-module-jwt.