跳转至

jwt: NGINX JWT 模块

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

  • RedHat Enterprise Linux 7、8、9 和 10
  • CentOS 7、8、9
  • AlmaLinux 8、9
  • Rocky Linux 8、9
  • Amazon Linux 2 和 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

通过在 /etc/nginx/nginx.conf 的顶部添加以下内容来启用模块：

load_module modules/ngx_http_auth_jwt_module.so;

本文档描述了 nginx-module-jwt v3.4.4，于 2026 年 2 月 03 日发布。

Nginx jwt 认证模块

License

这是一个用于检查有效 JWT 的 NGINX 模块，该模块旨在尽可能轻量并保持简单：

快速开始：

Docker 镜像：

镜像是通过 Github Actions 生成的（请参见 nginx-jwt-module:latest）

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

预构建包（Ubuntu / Debian）

此模块的预构建包可以从 GetPageSpeed 仓库免费获得：

## 添加仓库（Ubuntu 示例 - 根据您的发行版替换 'ubuntu' 和 'jammy'）
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; # 您的密钥以十六进制字符串表示
        auth_jwt     off;

        # 默认的认证方法是 "Authentication" 头
        location /secured-by-auth-header/ {
            auth_jwt on;
        }

        # 但您也可以使用 cookie
        location /secured-by-cookie/ {
            auth_jwt $cookie_MyCookieName;
        }

        # JWT 密钥从上一个配置级别继承
        # 但您可以为不同的位置使用不同的密钥
        location /secured-by-auth-header-too/ {
            auth_jwt_key "another-secret"; # 您的密钥以 utf8 字符串表示
            auth_jwt on;
        }

        location /secured-by-rsa-key/ {
            auth_jwt_key /etc/keys/rsa-public.pem file; # 您的密钥来自 PEM 文件
            auth_jwt on;
        }

        location /not-secure/ {}
    }
}

注意：不要忘记在主上下文中 加载 模块：

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

指令：

auth_jwt

语法:  auth_jwt $variable | on | off;
默认: auth_jwt off;
上下文: http, server, location

启用 JWT 的验证。

auth_jwt $variable 值可用于设置自定义方式获取 JWT，例如从 cookie 中获取，而不是默认的 Authentication 头：auth_jwt $cookie_MyCookieName;

auth_jwt_key

语法:  auth_jwt_key value [encoding];
默认: ——
上下文: http, server, location

指定用于验证 JWT 签名的密钥（必须是十六进制）。
编码 选项可以是 hex | utf8 | base64 | file（默认是 utf8）。
file 选项要求 value 为有效的文件路径（指向 PEM 编码的密钥）。

auth_jwt_alg

语法:  auth_jwt_alg any | HS256 | HS384 | HS512 | RS256 | RS384 | RS512 | ES256 | ES384 | ES512;
默认: auth_jwt_alg any;
上下文: http, server, location

指定服务器期望在 JWT 中接收的算法。

auth_jwt_require

语法:  auth_jwt_require $value ... [error=401 | 403];
默认: ——
上下文: http, server, location

指定 JWT 验证的附加检查。只有当所有值都不为空且不等于 “0” 时，认证才会成功。

这些指令仅在当前级别没有定义 auth_jwt_require 指令时，从上一个配置级别继承。

如果任何检查失败，将返回 401 错误代码。可选的错误参数允许将错误代码重新定义为 403。

示例：

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

请注意，由于 $jwt_claim_ 返回的是 JSON 编码的值，因此我们必须检查 \"value\"（而不是 value）

嵌入变量：

ngx_http_auth_jwt_module 模块支持嵌入变量：

  • $jwtheadername 返回指定头的值
  • $jwtclaimname 返回指定声明的值
  • $jwt_headers 返回头部
  • $jwt_payload 返回有效负载

请注意，由于所有返回的值都是 JSON 编码的，因此字符串将被 " 字符包围

扩展您的 Docker 镜像：

直接从 Github 生成的镜像创建您的镜像

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

## 复制您的 nginx 配置
## 不要忘记在您的配置中包含此模块
## 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;"]

或直接使用提供的镜像

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

或

docker build -f Dockerfile -t jwt-nginx . 

### 测试：

#### 默认用法：

```bash
make test # 将构建一个测试镜像并运行测试套件

示例配置：

在本节中，我们将看到一些如何使用此模块的示例。

如果 JWT 无效则重定向到登录页面：

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

## ...

http {
    server {
        listen 80;
        server_name _;

        auth_jwt_key "0123456789abcdef" hex; # 您的密钥以十六进制字符串表示
        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";
        }
    }
}

尝试 curl -i http://localhost/secure/path?param=value 将返回 302 重定向到 /login?redirect=/secure/path?param=value 如果 JWT 无效。

GitHub

您可以在 nginx-module-jwt 的 GitHub 仓库 中找到此模块的其他配置提示和文档。