模块 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 身份验证。

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

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

该模块支持以下 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 令牌的验证。指定的 字符串 用作 realm。参数值可以包含变量。

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

auth_jwt "closed site" token=$cookie_auth_token;

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

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

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

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

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

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

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

auth_jwt_key_cache 0;

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

指定一个 JSON Web 密钥集 格式的 文件，用于验证 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_名称

返回指定 JOSE 标头 的值。

$jwt_claim_名称

返回指定 JWT 声明 的值。

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

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

$jwt_payload

返回 nested 或 encrypted 令牌 (1.21.2) 的已解密顶层有效负载。对于嵌套令牌，返回封闭的 JWS 令牌。对于加密令牌，返回包含声明的 JSON。