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）和嵌套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 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 声明参数。名称匹配从 JSON 树的顶层开始。对于数组，变量保留由逗号分隔的数组元素列表。

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

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

使用 JWE 加密的令牌的变量值仅在解密期间（发生在Access阶段）后才可用。

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

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

auth_jwt_key_cache 0;

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

指定以JSON Web Key Set格式验证 JWT 签名的file。参数值可以包含变量。

同一级别上可以指定多个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;

设置用于验证JWT声明中的exp和nbf的最大允许偏移量以补偿时钟偏移。

auth_jwt_type signed;

指定要期望的JSON Web Token的类型：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。