模块 ngx_http_auth_jwt_module

该ngx_http_auth_jwt_module模块 (1.11.3) 通过 使用指定密钥验证提供的JSON Web 令牌(JWT) 来实现客户端授权。该模块支持 JSON Web 签名(JWS)、 JSON Web 加密(JWE) (1.19.7) 和嵌套 JWT (1.21.0)。该模块可用于 OpenID Connect 身份验证。

该模块可以通过satify指令 与其他访问模块组合，例如 ngx_http_access_module、 ngx_http_auth_basic_module和 ngx_http_auth_request_module。

该模块作为我们商业订阅 的一部分提供 。

该模块支持以下 JSON Web 算法。

JWS算法：

• HS256、HS384、HS512
• RS256、RS384、RS512
• ES256、ES384、ES512
• EdDSA（Ed25519 和 Ed448 签名）(1.15.7)

在1.13.7版本之前，仅支持HS256、RS256、ES256算法。

JWE 内容加密算法（1.19.7）：

• A128CBC-HS256、A192CBC-HS384、A256CBC-HS512
• A128GCM、A192GCM、A256GCM

JWE 密钥管理算法 (1.19.9)：

• A128KW、A192KW、A256KW
• A128GCMKW、A192GCMKW、A256GCMKW
• dir - 直接使用共享对称密钥作为内容加密密钥
• RSA-OAEP、RSA-OAEP-256、RSA-OAEP-384、RSA-OAEP-512 (1.21.0)

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

auth_jwt off;

启用 JSON Web 令牌的验证。指定string的用作realm. 参数值可以包含变量。

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

auth_jwt "closed site" token=$cookie_auth_token;

该特殊值取消了从先前配置级别继承的指令 off的效果。auth_jwt

将 设为variable由键名称标识的 JWT 声明参数。名称匹配从 JSON 树的顶层开始。对于数组，该变量保留以逗号分隔的数组元素列表。

auth_jwt_claim_set $email info e-mail;
auth_jwt_claim_set $job info "job title";

在 1.13.7 版本之前，只能指定一个键名，并且数组的结果未定义。

使用 JWE 加密的令牌的变量值仅在访问阶段 发生解密后才可用 。

将 设为variable由键名称标识的 JOSE 标头参数。名称匹配从 JSON 树的顶层开始。对于数组，该变量保留以逗号分隔的数组元素列表。

在 1.13.7 版本之前，只能指定一个键名，并且数组的结果未定义。

auth_jwt_key_cache 0;

启用或禁用从文件 或子请求 获取的密钥的缓存，并为其设置缓存时间。不支持缓存从变量获取的键。默认情况下，禁用密钥缓存。

指定JSON Web 密钥集file格式 用于验证 JWT 签名。参数值可以包含变量。

auth_jwt_key_file可以在同一级别上指定 多个指令 (1.21.1)：

auth_jwt_key_file conf/keys.json;
auth_jwt_key_file conf/key.jwk;

如果至少有一个指定的键无法加载或处理，nginx 将返回 500（内部服务器错误）错误。

允许从子请求中 检索 JSON Web 密钥集文件以验证 JWT 签名，并设置子请求将发送到的 URI。参数值可以包含变量。为了避免验证开销，建议缓存密钥文件：

proxy_cache_path /data/nginx/cache levels=1 keys_zone=foo:10m;

server {
    ...

    location / {
        auth_jwt             "closed site";
        auth_jwt_key_request /jwks_uri;
    }

    location = /jwks_uri {
        internal;
        proxy_cache foo;
        proxy_pass  http://idp.example.com/keys;
    }
}

auth_jwt_key_request可以在同一级别上指定 多个指令 (1.21.1)：

auth_jwt_key_request /jwks_uri;
auth_jwt_key_request /jwks2_uri;

如果至少有一个指定的键无法加载或处理，nginx 将返回 500（内部服务器错误）错误。

auth_jwt_leeway 0s;

设置验证exp 和 nbf JWT 声明 时补偿时钟偏差的最大允许余地 。

auth_jwt_type signed;

指定需要哪种类型的 JSON Web 令牌：JWS ( signed)、JWE ( encrypted) 或签名然后加密的嵌套 JWT ( nested) (1.21.0)。

指定 JWT 验证的附加检查。该值可以包含文本、变量及其组合，并且必须以变量开头 (1.21.7)。只有所有值不为空且不等于“0”时，认证才会成功。

map $jwt_claim_iss $valid_jwt_iss {
    "good" 1;
}
...

auth_jwt_require $valid_jwt_iss;

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

该ngx_http_auth_jwt_module模块支持嵌入变量：

$jwt_header_name

返回指定JOSE 标头 的值

$jwt_claim_name

返回指定JWT 声明 的值

对于嵌套声明和包含点（“.”）的声明，无法计算变量的值；应改用 auth_jwt_claim_set指令。

使用 JWE 加密的令牌的变量值仅在访问阶段 发生解密后才可用 。

$jwt_payload

nested 返回或encrypted令牌 (1.21.2) 的解密顶级有效负载。对于嵌套令牌，返回随附的 JWS 令牌。对于加密令牌，返回带有声明的 JSON。