当前位置：首页 > news >正文

NGINX 的 ngx_http_auth_jwt_module模块

news 来源：原创 2025/8/23 23:11:52

一、模块概述

ngx_http_auth_jwt_module 模块用于通过验证请求中提供的 JWT 来进行客户端授权。此模块支持 JSON Web 签名（JWS）、JSON Web 加密（JWE）以及嵌套 JWT（Nested JWT），使其成为一种灵活且安全的认证方案。它通常与其他访问控制模块（如 ngx_http_access_module、ngx_http_auth_basic_module 等）配合使用，提供多层次的访问控制。

二、支持的算法

该模块支持以下 JSON Web 算法（JWS 和 JWE）：

JWS 签名算法：
- HS256、HS384、HS512（HMAC SHA 算法）
- RS256、RS384、RS512（RSA 签名算法）
- ES256、ES384、ES512（ECDSA 签名算法）
- EdDSA（Ed25519 和 Ed448 签名算法）
JWE 内容加密算法：
- A128CBC-HS256、A192CBC-HS384、A256CBC-HS512
- A128GCM、A192GCM、A256GCM
JWE 密钥管理算法：
- RSA-OAEP、RSA-OAEP-256、RSA-OAEP-384、RSA-OAEP-512

三、配置示例

以下是一个基本的配置示例：

location / {auth_jwt "closed site";auth_jwt_key_file conf/keys.json;
}

在这个配置中，auth_jwt 启用了 JWT 验证，并指定了 JWT 密钥文件 keys.json 用于验证 JWT 签名。

四、主要指令

4.1. `auth_jwt`

语法：auth_jwt string [token=$variable] | off;
默认值：auth_jwt off;
上下文：http, server, location, limit_except

此指令用于启用 JWT 验证，string 参数指定了一个 Realm，作为认证域。你可以在这个值中使用变量。默认情况下，JWT 会在 Authorization 头部作为 Bearer Token 提供。如果你希望 JWT 通过其他方式传递（例如通过 cookie 或查询字符串），可以使用 token 参数。

auth_jwt "closed site" token=$cookie_auth_token;

4.2. `auth_jwt_key_file`

语法：auth_jwt_key_file file;
默认值：无
上下文：http, server, location, limit_except

此指令指定一个 JSON Web 密钥文件，用于验证 JWT 的签名。这个文件必须遵循 JSON Web Key Set (JWKS) 格式。多个 auth_jwt_key_file 指令可以同时使用，用来指定多个密钥文件。

auth_jwt_key_file /etc/nginx/keys.json;

4.3. `auth_jwt_claim_set`

语法：auth_jwt_claim_set $variable name ...;
默认值：无
上下文：http

该指令用于将 JWT 声明参数设置为指定的变量。声明参数可以是 JWT 中任何层级的键值对，支持数组，数组中的元素将以逗号分隔。

auth_jwt_claim_set $email info email;
auth_jwt_claim_set $role info role;

4.4. `auth_jwt_header_set`

语法：auth_jwt_header_set $variable name ...;
默认值：无
上下文：http

此指令用于将指定的 JWT 头部参数设置为变量。

4.5. `auth_jwt_key_request`

语法：auth_jwt_key_request uri;
默认值：无
上下文：http, server, location, limit_except

此指令允许通过子请求从指定 URI 获取 JSON Web 密钥集文件，用于验证 JWT 的签名。这种方式可以在需要时动态获取密钥，减少密钥管理的复杂性。

auth_jwt_key_request /jwks_uri;

4.6. `auth_jwt_leeway`

语法：auth_jwt_leeway time;
默认值：auth_jwt_leeway 0s;
上下文：http, server, location

此指令设置在验证 JWT 的 exp（过期时间）和 nbf（生效时间）声明时，允许的最大时间偏差。它有助于缓解因服务器时钟不一致导致的时间问题。

五、嵌入变量

ngx_http_auth_jwt_module 支持以下嵌入变量，方便在配置中使用：

$jwt_header_name：返回指定 JWT 头部的值。
$jwt_claim_name：返回指定 JWT 声明的值。
$jwt_payload：返回解密后的 JWT 内容。

六、结合其他模块使用

ngx_http_auth_jwt_module 模块可以与其他访问控制模块（如 ngx_http_access_module、ngx_http_auth_basic_module）结合使用。通过 satisfy 指令，可以实现灵活的访问控制。例如，既可以基于 JWT 进行身份验证，也可以基于 IP 地址进行限制：

location / {satisfy any;auth_jwt "closed site";auth_basic "restricted area";auth_basic_user_file /etc/nginx/.htpasswd;allow 192.168.1.0/24;deny all;
}

在这个示例中，访问控制同时依赖于 JWT 和 HTTP 基本认证，且仅允许从 192.168.1.0/24 网络段的请求。

七、总结

ngx_http_auth_jwt_module 模块为 NGINX 提供了强大的基于 JWT 的身份验证能力，支持多种算法，并且能灵活地与其他模块结合使用，实现复杂的访问控制策略。无论是在 OpenID Connect 认证还是微服务架构中，JWT 都能为你提供安全、轻量级的认证方式。

希望通过本文，大家能够更好地理解 ngx_http_auth_jwt_module 模块的配置和使用方式，为实现安全可靠的身份认证打下基础。

一、模块概述

二、支持的算法

三、配置示例

四、主要指令

4.1. auth_jwt

4.2. auth_jwt_key_file

4.3. auth_jwt_claim_set

4.4. auth_jwt_header_set

4.5. auth_jwt_key_request

4.6. auth_jwt_leeway