python_jwt module

python_jwt.generate_jwt(claims[, priv_key, ...])

Generate a JSON Web Token.

python_jwt.process_jwt(jwt)

Process a JSON Web Token without verifying it.

python_jwt.verify_jwt(jwt[, pub_key, ...])

Verify a JSON Web Token.

Functions for generating and verifying JSON Web Tokens.

python_jwt.generate_jwt(claims, priv_key=None, algorithm='PS512', lifetime=None, expires=None, not_before=None, jti_size=16, other_headers=None)

Generate a JSON Web Token.

Parameters:

  • claims (dict) – The claims you want included in the signature.

  • priv_key (jwcrypto.jwk.JWK) – The private key to be used to sign the token. Note: if you pass None then the token will be returned with an empty cryptographic signature and algorithm will be forced to the value none.

  • algorithm (str) – The algorithm to use for generating the signature. RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, HS256, HS384, HS512 and none are supported.

  • lifetime (datetime.timedelta) – How long the token is valid for.

  • expires (datetime.datetime) – When the token expires (if lifetime isn’t specified)

  • not_before (datetime.datetime) – When the token is valid from. Defaults to current time (if None is passed).

  • jti_size (int) – Size in bytes of the unique token ID to put into the token (can be used to detect replay attacks). Defaults to 16 (128 bits). Specify 0 or None to omit the JTI from the token.

  • other_headers (dict) – Any headers other than “typ” and “alg” may be specified, they will be included in the header.

Return type:

unicode

Returns:

The JSON Web Token. Note this includes a header, the claims and a cryptographic signature. The following extra claims are added, per the JWT spec:

  • exp (IntDate) – The UTC expiry date and time of the token, in number of seconds from 1970-01-01T0:0:0Z UTC.

  • iat (IntDate) – The UTC date and time at which the token was generated.

  • nbf (IntDate) – The UTC valid-from date and time of the token.

  • jti (str) – A unique identifier for the token.

Raises:

ValueError: If other_headers contains either the “typ” or “alg” header

python_jwt.process_jwt(jwt)

Process a JSON Web Token without verifying it.

Call this before verify_jwt() if you need access to the header or claims in the token before verifying it. For example, the claims might identify the issuer such that you can retrieve the appropriate public key.

Parameters:

jwt (str or unicode) – The JSON Web Token to verify.

Return type:

tuple

Returns:

(header, claims)

python_jwt.verify_jwt(jwt, pub_key=None, allowed_algs=None, iat_skew=datetime.timedelta(0), checks_optional=False, ignore_not_implemented=False)

Verify a JSON Web Token.

Parameters:

  • jwt (str or unicode) – The JSON Web Token to verify.

  • pub_key – The public key to be used to verify the token. Note: if you pass None and allowed_algs contains none then the token’s signature will not be verified.

  • allowed_algs (list or NoneType (meaning an empty list)) – Algorithms expected to be used to sign the token. The in operator is used to test membership.

  • iat_skew (datetime.timedelta) – The amount of leeway to allow between the issuer’s clock and the verifier’s clock when verifying that the token was generated in the past. Defaults to no leeway.

  • checks_optional (bool) – If False, then the token must contain the typ header property and the iat, nbf and exp claim properties.

  • ignore_not_implemented (bool) – If False, then the token must not contain the jku, jwk, x5u, x5c or x5t header properties.

Return type:

tuple

Returns:

(header, claims) if the token was verified successfully. The token must pass the following tests:

  • Its header must contain a property alg with a value in allowed_algs.

  • Its signature must verify using pub_key (unless its algorithm is none and none is in allowed_algs).

  • If the corresponding property is present or checks_optional is False:

    • Its header must contain a property typ with the value JWT.

    • Its claims must contain a property iat which represents a date in the past (taking into account iat_skew).

    • Its claims must contain a property nbf which represents a date in the past.

    • Its claims must contain a property exp which represents a date in the future.

Raises:

If the token failed to verify.

Indices and tables