模块 ngx_http_auth_jwt_module
支持的算法 配置示例 指令 auth_jwt auth_jwt_claim_set auth_jwt_header_set auth_jwt_key_cache auth_jwt_key_file auth_jwt_key_request auth_jwt_leeway auth_jwt_type auth_jwt_require 内嵌变量 |
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 |
---|---|
默认值 |
auth_jwt off; |
上下文 |
http , server , location , limit_except |
启用 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
指令的效果。
语法 |
auth_jwt_claim_set |
---|---|
默认值 | — |
上下文 |
http |
此指令出现于 1.11.10 版本。
将 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 阶段发生的解密之后可用。
语法 |
auth_jwt_header_set |
---|---|
默认值 | — |
上下文 |
http |
此指令出现于 1.11.10 版本。
将 variable
设置为由键名标识的 JOSE header 参数。名称匹配从 JSON 树的顶层开始。对于数组,变量保留以逗号分隔的数组元素列表。
在 1.13.7 版本之前,只能指定一个键名,且对于数组的结果是未定义的。
语法 |
auth_jwt_key_cache |
---|---|
默认值 |
auth_jwt_key_cache 0; |
上下文 |
http , server , location |
此指令出现于 1.21.4 版本。
启用或禁用从文件或从子请求获取的密钥的缓存,并设置其缓存时间。不支持缓存从变量获取的密钥。默认情况下,密钥缓存是禁用的。
语法 |
auth_jwt_key_file |
---|---|
默认值 | — |
上下文 |
http , server , location , limit_except |
指定一个采用 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) 错误。
语法 |
auth_jwt_key_request |
---|---|
默认值 | — |
上下文 |
http , server , location , limit_except |
此指令出现于 1.15.6 版本。
允许从子请求检索 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 |
---|---|
默认值 |
auth_jwt_leeway 0s; |
上下文 |
http , server , location |
此指令出现于 1.13.10 版本。
设置最大允许的宽限(leeway),用于补偿验证 exp 和 nbf JWT claims 时的时间偏差。
语法 |
auth_jwt_type |
---|---|
默认值 |
auth_jwt_type signed; |
上下文 |
http , server , location , limit_except |
此指令出现于 1.19.7 版本。
指定预期的 JSON Web Token 类型:JWS (signed
)、JWE (encrypted
),或先签名再加密的 Nested JWT (nested
) (1.21.0)。
语法 |
auth_jwt_require |
---|---|
默认值 | — |
上下文 |
http , server , location , limit_except |
此指令出现于 1.21.2 版本。
指定对 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。