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

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

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

load_module modules/ngx_http_auth_jwt_module.so;

本文档描述了 nginx-module-jwt v3.4.3，发布于 2025 年 3 月 14 日。

---

Nginx jwt 认证模块

这是一个用于检查有效 JWT 的 NGINX 模块，该模块旨在尽可能轻量并保持简单： - 基于 官方 nginx Dockerfile（alpine）的 Docker 镜像。 - 轻量镜像（比官方镜像多约 400KB）。

模块配置：

示例配置：

## 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 签名的密钥（必须是十六进制）。
encoding 选项可以是 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 错误代码。可选的 error 参数允许将错误代码重新定义为 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 模块支持嵌入变量： - $jwt_header_name 返回指定的头值 - $jwt_claim_name 返回指定的声明值 - $jwt_headers 返回头部 - $jwt_payload 返回有效负载

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

镜像：

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

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

直接从 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

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