python-jose: JOSE Implementation for Python

Warnings

• breaking Python 3.8 support was removed in version 3.5.0. Prior versions also removed support for Python 3.6/3.7 (v3.4.0) and 2.7/3.5 (v3.3.0).
  Fix: Upgrade to a supported Python version (3.9+ for python-jose 3.5.0).
• gotcha The default cryptographic backend for `python-jose` has changed across versions (PyCryptodome in 2.0.0, native Python `rsa` in 3.0.0). Since 3.3.0, while native backends (rsa/ecdsa) are always installed, `pyca/cryptography` is the recommended backend for performance and security. Not installing with `pip install python-jose[cryptography]` can lead to slower native Python implementations being used by default.
  Fix: Always install with `pip install python-jose[cryptography]` for production environments to ensure optimal performance and security. Review your installed dependencies to confirm `cryptography` is active.
• breaking Versions prior to 3.4.0 were vulnerable to Improper Handling of Highly Compressed Data (CVE-2024-33664, JWE size limit) and Improper Verification of Cryptographic Signature (CVE-2024-33663, signing JWT with public key forbidden).
  Fix: Upgrade to `python-jose` version 3.4.0 or higher immediately to patch critical security vulnerabilities.
• deprecated The usage of `datetime.utcnow()` was replaced with `datetime.now(UTC)` in version 3.4.0 due to `utcnow()` being deprecated in Python 3.11. Code relying on `utcnow()` with older versions might encounter deprecation warnings.
  Fix: Upgrade to `python-jose` 3.4.0+ to avoid `datetime.utcnow()` deprecation warnings and ensure future compatibility.
• gotcha Version 3.5.0 removed `get_random_bytes` from the `cryptography` backend and removed sensitive information from `JWKError` exceptions. If your code directly accessed `get_random_bytes` through the backend or relied on specific error message content from `JWKError`, this might be a breaking change.
  Fix: Review code for direct access to backend-specific utilities like `get_random_bytes` or reliance on `JWKError` message specifics. Adapt to the new behavior or use standard `os.urandom` if random bytes are needed.
• gotcha Some external resources suggest `python-jose` might be less actively maintained compared to alternatives like `PyJWT` or `joserfc` and recommend considering these for new projects or migrations. While `python-jose` still receives updates, this feedback indicates a potential concern for long-term support or advanced features.
  Fix: Evaluate your project's specific needs for JOSE implementation. If long-term maintenance, broader community support, or specific advanced features are critical, consider alternatives like `PyJWT` or `joserfc` (from Authlib), which may offer different API structures.

Install

• pip install python-jose Base installation (uses native Python backend)
• pip install python-jose[cryptography] Recommended for production (uses pyca/cryptography backend)

Imports

• jwt

  from jose import jwt

• jws

  from jose import jws

• jwe

  from jose import jwe

• jwk

  from jose import jwk

Quickstart

This quickstart demonstrates encoding and decoding a JSON Web Token (JWT) using a symmetric (HS256) algorithm. For asymmetric algorithms (like RS256), you would use public/private key pairs instead of a shared secret. Ensure `JWT_SECRET_KEY` is set securely in your environment for production use.

import os
from jose import jwt

# IMPORTANT: Use a strong, securely generated secret key in production
SECRET_KEY = os.environ.get('JWT_SECRET_KEY', 'your-super-secret-key-please-change-me')
ALGORITHM = "HS256"

# 1. Encode a JWT
payload = {"user_id": "123", "username": "testuser", "role": "admin"}
encoded_jwt = jwt.encode(payload, SECRET_KEY, algorithm=ALGORITHM)
print(f"Encoded JWT: {encoded_jwt}")

# 2. Decode and verify a JWT
try:
    decoded_payload = jwt.decode(encoded_jwt, SECRET_KEY, algorithms=[ALGORITHM])
    print(f"Decoded Payload: {decoded_payload}")
except Exception as e:
    print(f"Error decoding JWT: {e}")