Authlib (authlib.jose)

事实及其依据的检查

以下内容均非抄自文档。检查脚本 content/libraries/verify/authlib/run.sh 于2026年10月20日在容器镜像 python:3.14.8-slim-trixie 中运行了 Authlib (authlib.jose) 1.9.1（运行时为 cryptography 50.0.2）；本页内容必须与它的输出一致，每条事实都列出了对应的输出行。

• JOSE 模块的状态

  deprecated

  在 1.9.1 中导入 authlib.jose 会输出 authlib.jose module is deprecated, please use joserfc instead.

  检查记录

  fact jose-module-status = deprecated
  evidence jose-module-status: authlib.jose module is deprecated, please use joserfc instead.

• JWS 算法

  HS256HS384HS512RS256RS384RS512PS256PS384PS512ES256ES384ES512ES256KEdDSA

  256/384/512 位的 HS、RS、PS 和 ES，以及 ES256K 和 EdDSA，签名与验证均成功；Ed25519 和 Ed448 抛出 UnsupportedAlgorithmError。

  检查记录

  fact jws-algorithms = HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, ES256K, EdDSA
  evidence jws-algorithms: Ed25519: UnsupportedAlgorithmError: unsupported_algorithm: 
  evidence jws-algorithms: Ed448: UnsupportedAlgorithmError: unsupported_algorithm: 
  evidence jws-algorithms: algorithms the module-level authlib.jose.jwt accepts: ES256, ES256K, ES384, ES512, EdDSA, HS256, HS384, HS512, PS256, PS384, PS512, RS256, RS384, RS512

• ES256 签名编码

  raw

  ES256 签名是 64 字节的原始 r‖s。

  检查记录

  fact jws-ecdsa-encoding = raw

• JWS 中的 DER 签名

  rejected

  带 DER 编码 ES256 签名的令牌会报错 BadSignatureError: bad_signature。

  检查记录

  fact jws-der-signature = rejected
  evidence jws-der-signature: BadSignatureError: bad_signature: 

• 算法允许列表

  from-key

  模块级的 jwt 接受它支持的、适用于该密钥类型的任何算法：ES256 令牌用 EC 密钥验证通过，而用同一个 EC 密钥验证 RS256 令牌时报错 Invalid data for importing key。

  检查记录

  fact jwt-algorithm-allowlist = from-key
  evidence jwt-algorithm-allowlist: authlib.jose.jwt.decode on ES256: verified; RS256 token with an EC key: ValueError: Invalid data for importing key

• 未签名的令牌（alg none）

  opt-in

  默认的 jwt 对 alg: none 抛出 UnsupportedAlgorithmError，但 JsonWebToken(["none"]) 会让未签名的令牌验证通过。

  检查记录

  fact jwt-alg-none = opt-in
  evidence jwt-alg-none: default jwt with an EC key: UnsupportedAlgorithmError: unsupported_algorithm: 
  evidence jwt-alg-none: JsonWebToken(['none']): verified

• 把公钥用作 HMAC 密钥

  rejected

  把 PEM 公钥用作 HS256 密钥时，无论使用默认对象还是受限实例，都会抛出 ValueError: This key may not be safe to import。

  检查记录

  fact jwt-hmac-public-key = rejected
  evidence jwt-hmac-public-key: JsonWebToken(['HS256']) with PEM text as key: ValueError: This key may not be safe to import
  evidence jwt-hmac-public-key: default jwt with PEM text as key: ValueError: This key may not be safe to import

• 按 alg 检查曲线

  enforced

  用 P-384 密钥签名 ES256 时抛出 Key for "ES256" not supported, only "P-256" allowed。

  检查记录

  fact jwt-ecdsa-curve-check = enforced
  evidence jwt-ecdsa-curve-check: ValueError: Key for "ES256" not supported, only "P-256" allowed

• 解码时校验声明

  no

  对于一小时前就已过期的令牌，decode() 照样返回了它的声明；只有 claims.validate() 才会检查 exp、nbf、iss 和 aud。

  检查记录

  fact jwt-claims-validated-on-decode = no
  evidence jwt-claims-validated-on-decode: decode() of a token expired an hour ago without validate(): returned claims

• 默认时钟偏差

  0s

  validate() 默认不留宽限时间：三秒前过期的令牌被拒绝了。

  检查记录

  fact jwt-clock-skew = 0s

• 是否要求过期时间声明

  no

  不含 exp 的令牌通过了 validate()；要强制要求它，需在 claims_options 中把它标记为必需。

  检查记录

  fact jwt-exp-required = no

用法

import time

from authlib.jose import JsonWebKey, JsonWebToken

key = JsonWebKey.generate_key("EC", "P-256", is_private=True)
public_jwk = key.as_dict(is_private=False)

# A JsonWebToken instance restricted to ES256 instead of the permissive module-level jwt.
es256 = JsonWebToken(["ES256"])
token = es256.encode({"alg": "ES256"}, {"sub": "user-42", "iss": "https://auth.example.com", "exp": int(time.time()) + 600}, key)

claims = es256.decode(
    token,
    public_jwk,
    claims_options={"iss": {"essential": True, "value": "https://auth.example.com"}, "exp": {"essential": True}},
)
claims.validate(leeway=30)  # decode() checks only the signature; validate() checks the claims
print("sub:", claims["sub"])