模块 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 以 Bearer 令牌 的形式在“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 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（内部服务器错误）错误。

auth_jwt_leeway 0s;

设置最大允许的宽限期，以补偿验证 exp 和 nbf JWT 声明时的时钟偏移。

auth_jwt_type signed;

指定要预期的 JSON Web 令牌类型：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 头 的值

$jwt_claim_name

返回指定的 JWT 声明 的值

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

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

$jwt_payload

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