模块 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_auth_jwt_module

该模块可以与 其他访问模块，例如 ngx_http_access_module、ngx_http_auth_basic_module、 以及 ngx_http_auth_request_module， 通过 satisfy Directives。

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

该模块支持以下 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 令牌的验证。 指定的 用作 . Parameter value 可以包含变量。stringrealm

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

auth_jwt "closed site" token=$cookie_auth_token;

特殊值取消效果 Directives 继承自之前的配置级别。offauth_jwt

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

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

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

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

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

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

auth_jwt_key_cache 0;

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

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

多个Directives 可以在同一级别 （1.21.1） 上指定：auth_jwt_key_file

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

如果至少有一个指定的 key 无法加载或处理， nginx 将返回 500 （Internal Server Error） 错误。

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

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;
    }
}

多个Directives 可以在同一级别 （1.21.1） 上指定：auth_jwt_key_request

auth_jwt_key_request /jwks_uri;
auth_jwt_key_request /jwks2_uri;

如果至少有一个指定的 key 无法加载或处理， nginx 将返回 500 （Internal Server Error） 错误。

auth_jwt_leeway 0s;

设置允许的最大补偿余量 验证 exp 和 nbf JWT 声明时的 clock skew。

auth_jwt_type signed;

指定预期的 JSON Web 令牌类型： JWS （）、 JWE （）、 或签名后加密 嵌套的 JWT （） （1.21.0）。signedencryptednested

指定 JWT 验证的其他检查。 该值可以包含文本、变量及其组合 并且必须以变量 （1.21.7） 开头。 身份验证将仅成功 如果所有值都不为空且不等于 “0”。

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

auth_jwt_require $valid_jwt_iss;

如果任何检查失败， 返回错误代码。 可选参数 （1.21.7） 允许将错误代码重新定义为 。401error403

模块 支持嵌入式变量：ngx_http_auth_jwt_module

$jwt_header_name

返回指定 JOSE 标头的值

$jwt_claim_name

返回指定 JWT 声明的值

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

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

$jwt_payload

返回解密后的顶级有效负载 of 或标记 （1.21.2）。 对于嵌套令牌，返回包含的 JWS 令牌。 对于加密令牌，返回包含声明的 JSON。nestedencrypted