API Documentation

PyO3 Bindings to the jsonwebtoken library.

jwtoxide.encode(payload, key, algorithm='HS256', header=None)

Encode a set of claims into a Json Web Token (JWT).

Parameters:

payload (dict) – The claims to encode, must be json serializable.
key (Union[EncodingKey, str]) – The key to use for signing. This can be an EncodingKey or a string representing an utf-8 encoded secret key.
algorithm (str) – The algorithm to use for signing the token, by default uses “HS256”.

Returns:

The encoded token.

Return type:

str

Raises:

Exception: If an error occurs during encoding

jwtoxide.decode(token, key, validation_options)

Decode a JWT using the provided keys.

This is a lower level api. Most users should rely on KeyRing to decode tokens from a SSO provider.

Parameters:

token (str) – The JWT to decode.
key (Union[DecodingKey, str]) – The key to use for decoding. This can be an DecodingKey or a string representing an utf-8 encoded secret key.
validation_options (ValidationOptions) – The options for token validation.

Returns:

The decoded claims.

Return type:

dict

Raises:

InvalidTokenError: If the token fails validation.

class jwtoxide.ValidationOptions(aud, iss, sub=None, required_spec_claims=None, early_expiration_seconds=0, leeway_seconds=5, validate_exp=True, validate_nbf=True, validate_aud=True, algorithms=None, verify_signature=True)

Sets the validation options when decoding a JWT

Parameters:

aud (set[str], optional) – Optional; The required audience claim, if set to None then no checking is performed.
iss (set[str], optional) – Optional; The required issuer, typically the URL of an oauth provider, if set to None then no checking is performed.
sub (str, optional) – Optional; The required subject claim, if set to None then no checking is performed. Defaults to None.
required_spec_claims (set[str], optional) – The claims that are required to be present in the JWT. Note only checks for presences of the claim, does not validate the value. Defaults to {“exp”, “iat”, “nbf”}.
early_expiration_seconds (int, optional) – Reject a token some time (in seconds) before the exp to prevent expiration in transit over the network. The value is the inverse of leeway, subtracting from the validation time. Defaults to 0
leeway_seconds (int, optional) – The leeway for validating time based claims in second. Defaults to 5 seconds.
validate_exp (bool, optional) – Whether to validate the expiration time claim, defaults to True.
validate_nbf (bool, optional) – Whether to validate the not-before time claim, defaults to True.
validate_aud (bool, optional) – Whether to validate the audience claim, defaults to True.
algorithms (list[str], optional) – The algorithms that can be used, defaults to {“RS256”,”RS384”,”RS512”,”ES256”,”ES384”,”PS256”,”PS384”,”PS512”,”EdDSA”}.
verify_signature (bool, optional) – Whether to verify the signature, very dangerous to turn this off. Defaults to True.

class jwtoxide.DecodingKey

A key for validating a JWT signature.

Used by being passed into the decode function.

from_base64_secret()

Create a key from base64 encoded bytes.

Parameters:: content (str) – The secret key that hase been base64 encoded.
Returns:: The key.
Return type:: DecodingKey

from_ec_der()

Create a key from a EC DER file.

Parameters:: content (bytes) – The contents of a DER file.
Returns:: The key.
Return type:: DecodingKey

from_ec_pem()

Create a key from a EC PEM file.

Parameters:: content (str) – The contents of a PEM file.
Returns:: The key.
Return type:: DecodingKey

from_ed_der()

Create a key from a Ed DER file.

Parameters:: content (bytes) – The contents of a DER file.
Returns:: The key.
Return type:: DecodingKey

from_ed_pem()

Create a key from a Ed PEM file.

Parameters:: content (str) – The contents of a PEM file.
Returns:: The key.
Return type:: DecodingKey

from_jwk()

Create a key from a JSON Web Key (JWK).

Parameters:: jwk (Jwk) – The JWK.
Returns:: The key.
Return type:: DecodingKey

from_rsa_der()

Create a key from a RSA DER file.

Parameters:: content (bytes) – The contents of a DER file.
Returns:: The key.
Return type:: DecodingKey

from_rsa_pem()

Create a key from a RSA PEM file.

Parameters:: content (str) – The contents of a PEM file.
Returns:: The key.
Return type:: DecodingKey

from_secret()

Create a key from bytes.

Parameters:: content (bytes) – The secret key.
Returns:: The key.
Return type:: DecodingKey

class jwtoxide.EncodingKey

JSON Web Keys (JWKs)

class jwtoxide.Jwk

A JSON Web Key (JWK) that can be used to validate a JWT.

from_json()

Create a Jwk from a JSON string.

Parameters:

content (str) – The JSON string.

Returns:

The JWK.

Return type:

Jwk

Raises:

ValueError: If the JSON is invalid.

class jwtoxide.JwkSet

A set of JSON Web Keys (JWKs) that can be used to validate a JWT.

from_json()

Create a JwkSet from a JSON string.

Parameters:

content (str) – The JSON string.

Returns:

The JwkSet.

Return type:

JwkSet

Raises:

ValueError: If the JSON is invalid.
class jwtoxide.KeyRing
A set of JWKs that have been mapped to their key id.

This is primary API for validating JWTs from an oAuth2/OIDC provider.

Example:
from base64 import urlsafe_b64encode
import time

import jwt # get using `pip install PyJWT``

from jwtoxide import KeyRing, ValidationOptions

encoding_key = "secret"
k = urlsafe_b64encode(encoding_key.encode("utf-8")).decode("utf-8")
jwk_set_json = f"""{{  
"keys": [  
    {{
    "kty": "oct",  
    "alg": "HS256",  
    "k": "{k}",
    "kid": "key1"  
    }}
]
}}"""
data = {
    "sub": "1234567890",
    "exp": int(time.time()) + 60000,
    "iat": int(time.time()),
    "nbf": int(time.time()),
    "name": "John Doe",
    "aud": "test",
    "iss": "test-issuer",
}
encoded_jwt = jwt.encode(
    data, encoding_key, algorithm="HS256", headers={"kid": "key1"}
)
jwk_set = JwkSet.from_json(jwk_set_json)
key_ring = KeyRing.from_jwkset(jwk_set)

validation_options = ValidationOptions(
    aud={"test"}, iss={"test-issuer"}, algorithms=["HS256"]
)
claims = key_ring.decode(encoded_jwt, validation_options=validation_options)
decode(token, validation_options)

Decode a JWT token.

Parameters:

token (str) – The JWT to decode.

validation_options (ValidationOptions) – The options for token validation.

Returns:

The decoded claims.

Return type:

dict

Raises:

InvalidTokenError: If the token fails validation.

from_jwkset()

Create a KeyRing from a JwkSet.

Parameters:

jwkset (JwkSet) – The JwkSet.

Returns:

The KeyRing.

Return type:

KeyRing

Exceptions

class jwtoxide.InvalidTokenError

Base exception when a token fails validation.

class jwtoxide.DecodeError

Raised when a token cannot be decoded because it failed validation.

class jwtoxide.InvalidSignatureError

Raised when a token’s signature doesn’t match the one provided as part of the token.

class jwtoxide.MissingRequiredClaimError

Raised when a claim that is required to be present is not contained in the claimset.

class jwtoxide.ExpiredSignatureError

Raised when a token’s signature doesn’t match the one provided as part of the token.

class jwtoxide.InvalidIssuerError

Raised when a token’s iss claim does not match the expected issuer.

class jwtoxide.InvalidAudienceError

Raised when a token’s aud claim does not match one of the expected audience values.

class jwtoxide.InvalidSubjectError

Raised when a token’s sub claim does not match the expected subject.

class jwtoxide.ImmatureSignatureError

Raised when a token’s nbf claim represents a time in the future.

class jwtoxide.InvalidAlgorithmError

Raised When the algorithm in the header doesn’t match the one passed to decode or the encoding/decoding key used doesn’t match the alg requested