python-jose

python-jose is a Python implementation of the JavaScript Object Signing and Encryption (JOSE) family of standards — JSON Web Signature (JWS), JSON Web Encryption (JWE), JSON Web Key (JWK), and JSON Web Algorithm (JWA) — including a high-level jwt module for encoding and decoding JSON Web Tokens. It supports three interchangeable cryptographic backends (pyca/cryptography, pycryptodome, and a pure-Python native backend), letting applications choose their dependency footprint while keeping the same public API.

Because JWT-based authentication is ubiquitous in modern APIs and single-sign-on flows, python-jose is a common building block for verifying and issuing tokens in Python web frameworks, OAuth2/OIDC clients, and API gateways that need to validate signed or encrypted tokens from identity providers like Auth0, Okta, or a custom OAuth2 server.

What You Get

• A high-level jwt.encode() / jwt.decode() API supporting standard claims validation (expiry, audience, issuer) out of the box
• Lower-level jws and jwe modules for direct JSON Web Signature and JSON Web Encryption operations when the high-level JWT API isn’t sufficient
• jwk support for representing and loading RSA, EC, and symmetric keys, including JWK Set (JWKS) parsing for identity-provider public key rotation
• Three swappable cryptographic backends — pyca/cryptography (recommended), pycryptodome, and a dependency-light pure-Python native backend — selected via install extras
• Support for the full range of JOSE algorithms including RS256/384/512, ES256/384/512, HS256/384/512, and encryption algorithms for JWE

Common Use Cases

• Verifying JWT access tokens issued by an OAuth2/OIDC identity provider (Auth0, Okta, AWS Cognito) in a Python API backend
• Issuing signed JWTs for a custom authentication system, embedding claims like user ID, roles, and expiry
• Decrypting JWE-encrypted tokens or payloads exchanged between services that require confidentiality, not just integrity
• Validating and parsing JWKS (JSON Web Key Sets) to support key rotation for federated identity providers

Under The Hood

Architecture: The library is organized around the four JOSE primitives as top-level modules (jose/jws.py, jose/jwe.py, jose/jwk.py, jose/jwt.py), with jose/backends/ providing a strategy-pattern abstraction (base.py defines the interface; cryptography_backend.py, rsa_backend.py, ecdsa_backend.py, and native.py implement it) so the same signing/verification calls dispatch to whichever cryptographic library is installed, auto-detected at import time. jose/constants.py centralizes algorithm identifiers and jose/utils.py handles base64url encoding conventions used throughout JOSE. Tech Stack: Pure Python 3.9+, with ecdsa, rsa, and pyasn1 as always-installed native-backend dependencies, plus optional extras for cryptography or pycryptodome to swap in a faster/more standard backend; packaging uses setuptools with setup.cfg-driven metadata and a pyproject.toml build-backend declaration. Code Quality: The tests/ directory contains 21 test files covering each backend and JOSE primitive separately (e.g. backend-specific signature tests, cross-backend JWK conformance), with pytest-cov wired into CI (.codecov.yml) to track coverage; the multi-backend design forces test parity across three implementations, which is a meaningful correctness safeguard for a cryptography library. API Design: The jwt.encode()/jwt.decode() functions mirror the ergonomics of the popular PyJWT library closely, requiring only a payload dict, key, and algorithm string to get started, while the lower-level jws/jwe modules are available for applications needing direct control over JOSE primitives beyond the JWT convenience wrapper.