如何在Nginx配置中实现TOKEN有效性验证？

Question

如何在Nginx中通过Lua或外部子请求验证JWT Token的有效性？常见问题包括：如何配置Nginx结合lua-resty-jwt或使用auth_request模块向后端认证服务校验Token；如何处理Token过期、签名无效等异常；以及如何将解析后的用户信息传递给后端应用。此外，动态黑名单（如退出登录的Token）与Redis集成也常成为实现难点。

Answer 1

一、JWT Token 验证在 Nginx 中的实现路径概览

在现代微服务架构中，Nginx 常作为反向代理网关，承担流量路由与安全校验职责。JWT（JSON Web Token）因其无状态特性被广泛用于用户身份认证。然而，直接在 Nginx 层面验证 JWT 并非原生支持功能，需借助 Lua 脚本或 auth_request 模块实现。

常见实现方式有两种：

1. Lua + OpenResty：利用 lua-resty-jwt 库在 Nginx 内部完成解析与校验。
2. auth_request 模块：通过子请求调用外部认证服务（如 OAuth2 Server）进行集中式校验。

以下将从配置到异常处理，逐步深入分析两种方案的技术细节与最佳实践。

二、基于 Lua 的 JWT 校验：OpenResty 与 lua-resty-jwt 集成

OpenResty 是集成了 LuaJIT 和多种 Lua 模块的 Nginx 发行版，适合执行复杂逻辑。

步骤如下：

• 安装 OpenResty 及依赖：luarocks install lua-resty-jwt
• 配置 Nginx 使用 Lua 脚本拦截请求并校验 Token

worker_processes  1;
events { worker_connections 1024; }

http {
    lua_package_path "/usr/local/share/lua/5.1/?.lua;;";

    server {
        listen 8080;

        location /api/ {
            access_by_lua_block {
                local jwt = require "resty.jwt"
                local jwt_secret = "your-256-bit-secret"

                local token = ngx.req.get_headers()["Authorization"]
                if not token then
                    ngx.status = 401
                    ngx.say("Missing Authorization header")
                    ngx.exit(ngx.HTTP_UNAUTHORIZED)
                end

                token = string.match(token, "Bearer (.+)")
                if not token then
                    ngx.status = 401
                    ngx.say("Invalid token format")
                    ngx.exit(ngx.HTTP_UNAUTHORIZED)
                end

                local jwt_obj = jwt:verify(jwt_secret, token)
                if not jwt_obj.verified then
                    ngx.status = 401
                    ngx.say("Token verification failed: " .. jwt_obj.reason)
                    ngx.exit(ngx.HTTP_UNAUTHORIZED)
                end

                -- 将用户信息注入请求头
                ngx.req.set_header("X-User-ID", jwt_obj.payload.sub)
                ngx.req.set_header("X-User-Roles", jwt_obj.payload.roles)
            }

            proxy_pass http://backend_app;
        }
    }
}

三、使用 auth_request 模块实现外部子请求校验

适用于已有认证中心的企业架构，避免在 Nginx 中维护密钥。

配置项	说明
auth_request	指定认证服务地址
auth_request_set	提取响应头中的用户信息
error_page 401	自定义未授权响应

location /api/ {
    auth_request /auth-validate;

    auth_request_set $user_id $upstream_http_x_user_id;
    auth_request_set $roles   $upstream_http_x_user_roles;

    proxy_set_header X-User-ID $user_id;
    proxy_set_header X-Roles $roles;

    proxy_pass http://backend_app;
}

location = /auth-validate {
    internal;
    proxy_pass http://auth-service/validate;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

四、异常处理机制设计

JWT 校验过程中可能遇到多种异常情况，需分类处理：

1. 签名无效：密钥不匹配或篡改，应返回 401
2. 过期 Token：检查 exp 字段，建议提前刷新
3. 格式错误：非 Bearer 或结构损坏
4. 黑名单 Token：已登出但未到期，需结合 Redis 查询

在 Lua 中可捕获具体错误类型：

if jwt_obj.reason == "expired" then
    ngx.status = 401
    ngx.header["X-Auth-Error"] = "Token expired"
elseif jwt_obj.reason == "invalid signature" then
    ngx.header["X-Auth-Error"] = "Tampered token"
end

五、动态黑名单与 Redis 集成方案

标准 JWT 无法主动失效，需引入“短生命周期 + 黑名单”机制。

流程图如下：

graph TD A[收到请求] --> B{提取JWT} B --> C[解析JTI] C --> D[查询Redis是否存在JTI] D -- 存在 --> E[拒绝访问] D -- 不存在 --> F[验证签名与时效] F --> G[放行并缓存JTI至过期时间]

Redis 集成代码示例：

local redis = require "resty.redis"
local red = redis:new()
red:connect("127.0.0.1", 6379)

local jti = jwt_obj.payload.jti
local blacklisted, err = red:get("jwt:blacklist:" .. jti)
if blacklisted == "1" then
    ngx.status = 401
    ngx.say("Token revoked")
    ngx.exit(ngx.HTTP_UNAUTHORIZED)
end

注销时由应用调用接口将 JTI 写入 Redis：

SET jwt:blacklist:<jti> "1" EX <remaining_ttl>

六、性能优化与安全增强建议

高并发场景下需注意：

• 启用 Lua 缓存减少重复解析
• 使用共享内存字典（shared_dict）缓存公钥或频繁验证结果
• 限制请求频率防止暴力破解
• 采用非对称加密（RSA）提升密钥安全性
• 定期轮换签名密钥并支持多版本共存

Nginx 配置共享内存：

http {
    lua_shared_dict jwt_cache 10m;
    lua_shared_dict redis_pool 5m;
}