Nginx官方文档(十三)【HTTP之ngx_http_auth_jwt_module|ngx_http_auth_request_module】

最新推荐文章于 2025-11-14 17:42:03 发布

转载最新推荐文章于 2025-11-14 17:42:03 发布 · 1.4k 阅读

3 ·

CC 4.0 BY-SA版权

原文链接：https://blog.youkuaiyun.com/WuLex

(Nginx|Haproxy)【IIS】专栏收录该内容

90 篇文章

订阅专栏

本文介绍Nginx的ngx_http_auth_jwt_module模块如何使用JSON Web Token(JWT)进行客户端授权验证，同时覆盖了ngx_http_auth_request_module模块基于子请求结果的授权方式。

ngx_http_auth_jwt_module 模块（1.11.3）通过验证使用指定的密钥提供的 JSON Web Token（JWT）来实现客户端授权。JWT claims 必须以 JSON Web Signature（JWS）结构编码。该模块可用于 OpenID Connect 身份验证。

该模块可以通过 satisfy 指令与其他访问模块（如 ngx_http_access_module、ngx_http_auth_basic_module 和 ngx_http_auth_request_module）进行组合。

此模块可作为我们商业订阅的一部分。

示例配置

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

指令

auth_jwt

-	说明
语法	auth_jwt `string [token=$variable]` \| `off`;
默认	auth_jwt off;
上下文	http、server、location

启用 JSON Web Token 验证。指定的字符串作为一个 realm。参数值可以包含变量。

可选的 token 参数指定一个包含 JSON Web Token 的变量。默认情况下，JWT 作 Bearer Token 在 Authorization 头中传递。JWT 也可以作为 cookie 或查询字符串的一部分传递：

auth_jwt "closed site" token=$cookie_auth_token;

特殊值 off 取消从上一配置级别继承的 auth_jwt 指令的作用。

auth_basic_user_file

-	说明
语法	auth_jwt_header_set `$variable name`;
默认	——
上下文	http
提示	该指令在 1.11.10 版本中出现

将 variable 设置为给定的 JOSE 头参数 name。

auth_jwt_claim_set

-	说明
语法	auth_jwt_claim_set `$variable name`;
默认	——
上下文	http
提示	该指令在 1.11.10 版本中出现

将 variable 设置为给定的 JWT claim 参数 name。

auth_jwt_key_file

-	说明
语法	auth_jwt_key_file `file`;
默认	——
上下文	http、server、location

指定用于验证 JWT 签名的 JSON Web Key Set 格式的 file（文件）。参数值可以包含变量。

内嵌变量

ngx_http_auth_jwt_module 模块支持内嵌变量：

$jwt_header_name

返回 JOSE 头的值
$jwt_claim_name

返回 JWT claim 的值

原文档

http://nginx.org/en/docs/http/ngx_http_auth_jwt_module.html

ngx_http_auth_request_module

示例配置
指令
- auth_request
- auth_request_set

ngx_http_auth_request_module 模块（1.5.4+）基于子请求结果实现客户端授权。如果子请求返回一个 2xx 响应代码，则允许访问。如果返回 401 或 403，则拒绝访问并抛出相应的错误代码。子请求返回的任何其他响应代码被认为是一个错误。

对于 401 错误，客户端也从子请求响应中接收 WWW-Authenticate 头。

该模块不是默认构建，应该在构建时使用 --with-http_auth_request_module 配置参数启用。

该模块可以通过 satisfy 指令与其他访问模块（如 ngx_http_access_module、ngx_http_auth_basic_module 和 ngx_http_auth_jwt_module）进行组合。

在 1.7.3 版本之前，无法缓存对授权子请求的响应（使用 proxy_cache、proxy_store 等）。

示例配置

location /private/ {
    auth_request /auth;
    ...
}

location = /auth {
    proxy_pass ...
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}