JOSE RFCs Implementation

Warnings

• breaking The deprecated `joserfc.rfcXXXX` modules (e.g., `joserfc.rfc7797` for JWS compact serialization/deserialization) were removed in favor of direct usage of modules like `joserfc.jws`.
  Fix: Update import paths and usage to directly use methods from `joserfc.jws`, `joserfc.jwe`, etc. For instance, `joserfc.jws.serialize_compact` instead of `joserfc.rfc7797.serialize_compact`.
• breaking `jwt.ClaimsRegistry` was renamed to `jwt.BaseClaimsRegistry`.
  Fix: Adjust import statements and class instantiations to use `BaseClaimsRegistry`.
• breaking Error classes related to JWT claims and JWS/JWE operations have changed significantly. `InvalidTokenError` and `ExpiredTokenError` were deprecated in favor of `InvalidClaimError`, and `ValueError` in JWS/JWE registries was replaced by `UnsupportedAlgorithmError`. Other new specific errors like `MissingKeyTypeError` and `InvalidKeyIdError` were introduced.
  Fix: Review error handling code to catch the new, more specific exception types. Use `InvalidClaimError` for JWT claim validation failures.
• gotcha Unlike some other JWT libraries (e.g., `PyJWT`), `joserfc` separates token decoding from claims validation. The `.decode()` method only extracts header and payload; explicit validation using `jwt.JWTClaimsRegistry` is required.
  Fix: Always perform claims validation explicitly after decoding a token, for example, by creating an instance of `jwt.JWTClaimsRegistry` and calling its `validate` method on the token's claims.
• gotcha `joserfc` does not provide a built-in HTTP client for fetching JWK Sets from a URL (e.g., from an OpenID Connect discovery endpoint).
  Fix: Use a third-party HTTP client library like `requests` to retrieve JWK Sets from URLs, then use `jwk.JsonWebKey.import_key_set()` to load them.
• gotcha Security warnings are now shown when importing potentially weak `OctKey` and `RSAKey` instances, typically if the key size is insufficient.
  Fix: Ensure you are using sufficiently strong keys (e.g., RSA keys of at least 2048 bits, preferably 4096 bits, and symmetric keys of appropriate length for the chosen algorithm) to avoid these warnings and maintain security.

Install

• pip install joserfc Install joserfc

Imports

• jwt, jwk

  from joserfc import jwt, jwk

• RSAKey

  from joserfc.jwk import RSAKey

• serialize_compact, deserialize_compact

  from joserfc.jws import serialize_compact, deserialize_compact

  Deprecated rfc modules were removed in v1.4.0; use the direct jws module instead.
• ClaimsRegistry

  from joserfc.jwt import BaseClaimsRegistry

  Renamed to BaseClaimsRegistry in v1.4.0.

Quickstart

This quickstart demonstrates how to encode and decode a JSON Web Token (JWT) using a symmetric key. It also includes an example of explicit claims validation, which is a crucial step for production environments.

import os
from joserfc import jwt, jwk

# For demonstration, use a simple symmetric key. In production, use a secure, generated key.
secret_key = os.environ.get('JOSERFC_SECRET_KEY', 'your-super-secret-key-that-is-at-least-32-chars')

# 1. Import or generate a JWK
# For symmetric keys, use 'oct' (octet) key type
key = jwk.import_key(secret_key, 'oct')

# 2. Define JWT header and claims
header = {"alg": "HS256", "typ": "JWT"}
claims = {"sub": "1234567890", "name": "John Doe", "iat": 1516239022}

# 3. Encode the JWT
encoded_jwt = jwt.encode(header, claims, key)
print(f"Encoded JWT: {encoded_jwt}")

# 4. Decode the JWT
token = jwt.decode(encoded_jwt, key)
print(f"Decoded Header: {token.header}")
print(f"Decoded Claims: {token.claims}")

# 5. Validate claims (important for production)
claims_registry = jwt.JWTClaimsRegistry()
try:
    claims_registry.validate(token.claims, now=1516239022) # 'now' for reproducible example
    print("Claims validated successfully.")
except jwt.InvalidClaimError as e:
    print(f"Claim validation failed: {e}")