Python JOSE 实现详解：使用 python-jose 进行 JWT 签名与验证

脚本专家

在 Python 项目中处理 JSON Web Token（JWT）签名、验证或加密时，python-jose 是一个功能较为完整的库，它实现了 JOSE 规范的核心组件，包括 JSON Web Signature (JWS)、JSON Web Encryption (JWE)、JSON Web Key (JWK) 和 JSON Web Algorithms (JWA)。该库在 GitHub 上获得 1752 个 Star，最初基于 PyJWT 实现，适合需要执行 JWT 或 JOSE 相关操作的开发者。

本文将重点介绍 python-jose 的加密后端选择、安装方式，以及最基础的 JWT 编码与解码用法。

一、加密后端选择与安装

python-jose 提供了三种加密后端，实际项目中推荐优先使用 cryptography 后端。安装时通过 pip 指定 extras 即可。

1. cryptography 后端（推荐）

使用 pyca/cryptography 库完成所有加密操作。如果系统中同时安装了多个后端，此后端默认被优先使用。

安装命令：

2. pip install python-jose[cryptography]

复制代码

安装后，环境中会遗留 rsa、ecdsa 和 pyasn1 三个未使用的依赖，建议在生产环境中手动清理。

2. pycryptodome 后端

使用 pycryptodome 库作为加密方案。

安装命令：

2. pip install python-jose[pycryptodome]

复制代码

安装后，rsa 会作为未使用的依赖保留。

3. native-python 后端

使用 python-rsa 和 python-ecdsa 进行加密操作。此后端始终会被安装，但若存在其他后端，则不会被优先使用。它有一个限制：无法处理证书相关操作。

安装命令（默认）：

2. pip install python-jose

复制代码

注意：由于 setuptools 的复杂性，即使安装时指定了其他后端，native-python 后端仍会被同时安装。开发者需在生产环境中手动移除不必要的依赖。

二、核心用法：JWT 编码与解码

python-jose 的 API 设计简洁，以下示例演示了如何使用 HMAC SHA-256 算法生成和验证 JWT token。

2. from jose import jwt
4. # 编码生成 token
5. payload = {'key': 'value'}
6. secret = 'secret'
7. algorithm = 'HS256'
8. token = jwt.encode(payload, secret, algorithm=algorithm)
9. print(token)  # 输出类似: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
11. # 解码验证 token
12. decoded = jwt.decode(token, secret, algorithms=['HS256'])
13. print(decoded)  # 输出: {'key': 'value'}

复制代码

参数说明：
- payload：要签名的数据，通常为字典格式，包含用户标识或自定义声明（claims）。
- secret：用于签名的密钥。在生产环境中应使用强度足够的密钥，并妥善保管。
- algorithm：指定签名算法，如 HS256、RS256 等。encode 时传入单个字符串，decode 时传入允许的算法列表。

decode 方法会自动验证签名和过期时间等标准声明（若 payload 中包含 exp 等字段），验证失败则抛出异常。

三、适用场景

当 Python 项目需要生成 JWT 用于身份认证、API 鉴权、数据传输加密签名，或者需要处理 JWE、JWK、JWA 等 JOSE 规范其他组件时，python-jose 提供了一套完整的解决方案。文档托管在 ReadTheDocs 上，代码覆盖率由 Codecov 持续追踪，CI 通过 GitHub Actions 运行。

建议新手优先选择 cryptography 后端以获得最佳兼容性和性能，同时注意生产环境的依赖清理。

热心网友4

感谢分享，写得非常清晰实用！之前我也试过 python-jose，cryptography 后端确实稳定很多。想问一下，关于生产环境清理依赖，你是直接用 pip uninstall 手动移除，还是有什么自动化工具推荐？另外，代码中 decode 部分如果 payload 带 exp，除了自动抛异常，有没有办法自定义过期时间的容差处理？

热心网友4

感谢分享，写得很清晰！之前用过 PyJWT，对 python-jose 的后端选择一直有些模糊，你这篇把 cryptography、pycryptodome 和 native-python 的区别点讲得很明白，特别是推荐优先用 cryptography 以及生产环境清理多余依赖的提醒，非常实用。我有个小问题：如果项目中同时需要验证多种算法（比如 HS256 和 RS256），decode 时传入的 algorithms 列表是支持这么做的对吧？另外，你提到 native-python 后端无法处理证书相关操作，能具体举个常见场景吗？再次感谢！

热心网友4

非常感谢脚本专家的详细分享！这篇教程把 python-jose 的安装后端选择、基础 API 用法讲得非常清楚，尤其是指出不同后端的依赖残留问题，对生产环境的优化很有帮助。我之前只知道用 PyJWT，现在看到 python-jose 能同时覆盖 JWS、JWE、JWK 等，感觉在需要加密或密钥管理的场景下会更灵活。 想请教一下，如果使用 RS256 非对称签名，在 encode 和 decode 时密钥的传入方式是不是跟 HS256 类似？另外，decode 自动验证 exp 过期时间时，是否需要额外配置 leeway 参数来允许一定时间偏差？期待能进一步补充这些细节！