Skip to main content

JWT support for Cromlech

Project description

JSON WebTokens utilities for web applications. Can produce and verify signed and encrypted tokens, with or without storage or self-deprecation.


In order to use the cryptographic capabilities, we create a cryptographic key. This key needs to be stored in order to be reused in your app. Make sure it’s stored in a safe place as tokens rely on this to be considered “secure”.

>>> from cromlech.jwt.components import JWTHandler
>>> key = JWTHandler.generate_key()

Read more here : Key generation options available : key type, size.

You can load a key from the key value and the type :

>>> key_string = JWTHandler.dump_key(key)
>>> key = JWTHandler.load_key(key_string)


The handler class is the carrier of the first layer of utilities. A handler instance can be configured to generate self-deprecating tokens.

By default, tokens have no expiration. Tokens with no expiration date can be stored and managed in your own application layer, implementing your own timeout mechanism and policy.

>>> handler = JWTHandler()
>>> data = {"user": "Cromlech User"}
>>> payload = handler.create_payload(**data)
>>> sorted(payload.items())  # doctest: +ALLOW_UNICODE
[('uid', '...'), ('user', 'Cromlech User')]

Configuring the timeout triggers the creation of an expiration time. The timeout is an integer representing the lifespan in minutes.

>>> handler = JWTHandler(auto_timeout=60)
>>> payload = handler.create_payload(**data)
>>> sorted(payload.items())  # doctest: +ALLOW_UNICODE
[('exp', ...), ('uid', '...'), ('user', 'Cromlech User')]

Note that an UID attribute is created by default. The base policy is to create an UID based on UUID (uuid4 here). You can override that method easily in a subclass.


The service class provides a wrapper around a handler to ease the common operations. It allows you to configure a handler, generate and authenticate. Furthermore, it has a skeleton structure to store and refresh, if you wish to create your own token policy.

>>> from cromlech.jwt.components import JWTService
>>> service = JWTService(key, JWTHandler)
>>> service.handler.auto_timeout
>>> import six
>>> token = service.generate(data)
>>> assert isinstance(token, six.string_types)
>>> import json
>>> token_data = handler.decrypt_and_verify(key, token)
>>> sorted(json.loads(token_data).items())  # doctest: +ALLOW_UNICODE
[('exp', ...), ('uid', '...'), ('user', 'Cromlech User')]
>>> auth_data = service.check_token(token)
>>> sorted(auth_data.items())  # doctest: +ALLOW_UNICODE
[('exp', ...), ('uid', '...'), ('user', 'Cromlech User')]
>>> import pytest
>>> from cromlech.jwt.components import InvalidToken
>>> with pytest.raises(InvalidToken) as invalid:
...     service.check_token(token + 'some_altering_data')

We can override the payload auto-generated data, to gain flexibility:

>>> data = {"user": "Cromlech User", "uid": "My Own ID"}
>>> token = service.generate(data)
>>> token_data = handler.decrypt_and_verify(key, token)
>>> sorted(json.loads(token_data).items())  # doctest: +ALLOW_UNICODE
[('exp', ...), ('uid', 'My Own ID'), ('user', 'Cromlech User')]

This way, we create an intentionally deprecated token to test:

>>> from cromlech.jwt.utils import get_posix_timestamp, expiration_date
>>> deprecated = get_posix_timestamp(expiration_date(-60))
>>> data = {"user": "Cromlech User", "exp": deprecated}
>>> token = service.generate(data)
>>> from cromlech.jwt.components import ExpiredToken
>>> with pytest.raises(ExpiredToken):
...     token_data = handler.decrypt_and_verify(key, token)

Note that, if your handler is not configured for self-deprecation, adding an expiration date on your payload will generate an error:

>>> service = JWTService(key, JWTHandler, auto_deprecate=False)
>>> deprecated = get_posix_timestamp(expiration_date(60))
>>> data = {"user": "Cromlech User", "exp": deprecated}
>>> from cromlech.jwt.components import InvalidPayload
>>> with pytest.raises(InvalidPayload) as payload_error:
...     token = service.generate(data)
>>> payload_error.value
InvalidPayload('Expiration is not allowed.',)


0.1 (2018-08-27)

  • Initial release

Project details

Release history Release notifications

This version
History Node


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
cromlech.jwt-0.1.tar.gz (6.3 kB) Copy SHA256 hash SHA256 Source None Aug 27, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page