模块 ngx_http_auth_jwt_module

ngx_http_auth_jwt_module 模块 (1.11.3) 通过使用指定的密钥验证提供的 JSON Web Token (JWT) 来实现客户端授权。该模块支持 JSON Web Signature (JWS)、JSON Web Encryption (JWE) (1.19.7) 和 Nested JWT (1.21.0)。该模块可用于 OpenID Connect 认证。

该模块可通过 satisfy 指令与通过其他访问模块组合使用，例如 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 Token 的验证。指定的 string 用作 realm。参数值可以包含变量。

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

auth_jwt "closed site" token=$cookie_auth_token;

特殊值 off 取消继承自上一配置级别的 auth_jwt 指令的效果。

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

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

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

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

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

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

auth_jwt_key_cache 0;

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

指定一个采用 JSON Web Key Set 格式的 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 (Internal Server Error) 错误。

允许从子请求检索 JSON Web Key Set 文件用于验证 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 (Internal Server Error) 错误。

auth_jwt_leeway 0s;

设置最大允许的宽限（leeway），用于补偿验证 exp 和 nbf JWT claims 时的时间偏差。

auth_jwt_type signed;

指定预期的 JSON Web Token 类型：JWS (signed)、JWE (encrypted)，或先签名再加密的 Nested 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 header 的值

$jwt_claim_name

返回指定的 JWT claim 的值

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

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

$jwt_payload

返回 nested 或 encrypted 令牌的解密后的顶层 payload (1.21.2)。对于 nested 令牌，返回其中包含的 JWS 令牌。对于 encrypted 令牌，返回带有 claims 的 JSON。