Metadata-Version: 1.1
Name: gocept.webtoken
Version: 3.1.post1
Summary: Wrapper around JWT tokens and the Zope Component Architecture (ZCA).
Home-page: https://github.com/gocept/gocept.webtoken
Author: gocept <mail@gocept.com>
Author-email: mail@gocept.com
License: MIT
Description: ================================
        The gocept.webtoken distribution
        ================================
        
        .. image:: https://travis-ci.com/gocept/gocept.webtoken.svg?branch=master
            :target: https://travis-ci.com/gocept/gocept.webtoken
        .. image:: https://coveralls.io/repos/github/gocept/gocept.webtoken/badge.svg
            :target: https://coveralls.io/github/gocept/gocept.webtoken
        
        
        This library helps you using JWT tokens with the Zope Component Architecture
        (ZCA).
        
        This package is compatible with Python version 2.7, 3.6 up to 3.8.
        
        Copyright (c) 2015-2020 gocept gmbh & co kg
        
        All Rights Reserved.
        
        This software is subject to the provisions of the Zope Public License,
        Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
        THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
        WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
        FOR A PARTICULAR PURPOSE.
        
        Installation
        ============
        
        This package requires ``cryptography``, which needs some install attention.
        Please refer to its `install documentation`_ for further information.
        
        
        .. _`install documentation`: https://cryptography.io/en/latest/installation/
        
        .. contents::
        
        Usage
        =====
        
        The ``CryptographicKey`` utility
        --------------------------------
        
        ``gocept.webtoken`` uses a global utility of the class
        ``gocept.webtoken.CryptographicKeys``, which provides cryptographic keys for
        different purposes. It loads a set of public and private keys from disk. It
        takes the filesystem path to your key files and a list of key names::
        
            >>> import gocept.webtoken
            >>> import pkg_resources
            >>> path_to_keys = pkg_resources.resource_filename(
            ...     'gocept.webtoken', 'testing/keys')
            >>> keys = gocept.webtoken.CryptographicKeys(
            ...     path_to_keys, ['key1'])
        
        For each of the names, a private key file of the same name and a public key
        file (with a .pub suffix) must reside inside the keys_dir.
        
        The utility needs to be registered at the ZCA, either via a zcml file or via::
        
            >>> import zope.component
            >>> zope.component.provideUtility(keys)
        
        
        Creating a token
        ----------------
        
        Create a signed web token with the function ``create_web_token``. You will need
        the private key name, which was registered at the CryptographycKey utility. It
        is referenced by its name and the suffix ``-private``::
        
            >>> expires_in = 300  # The token is valid for 300 seconds
            >>> payload = {'your': 'data'}
            >>> result = gocept.webtoken.create_web_token(
            ...     'key1-private', 'issuer', 'subject', expires_in, payload)
            >>> sorted(result.keys())
            ['data', 'token']
        
        The token is available under the key ``token``, while the data encoded in the
        token is placed under the key ``data``.
        
        
        Creating a Bearer Authorization header
        --------------------------------------
        
        You can create an `Bearer Authorization header`_ either from a token_dict as
        returned by create_web_token or from a token directly::
        
            >>> gocept.webtoken.create_authorization_header(b'<TOKEN>')
            ('Authorization', 'Bearer <TOKEN>')
        
        .. _`Bearer Authorization header`: https://tools.ietf.org/html/rfc6750#section-2.1
        
        Extracting a token from a Bearer Authorization header
        -----------------------------------------------------
        
        Extract the token from a dict containing the headers of you request or from the
        value of the HTTP Authorization header itself::
        
            >>> request_headers = dict(Authorization='Bearer <TOKEN>')
            >>> b'<TOKEN>' == gocept.webtoken.extract_token(request_headers)
            True
        
        
        Decoding a token
        ----------------
        
        Decode a signed web token with the function ``decode_web_token``. You will need
        the public key name, which was registered at the CryptographycKey utility. It
        is referenced by its name and the suffix ``-public``::
        
            >>> result = gocept.webtoken.decode_web_token(
            ...     result['token'], 'key1-public', 'subject')
        
        Note that the subject must match the subject given when the token was created.
        
        The result contains all data encoded in the token. You can find the payload
        under the key ``data``::
        
            >>> {'your': 'data'} == result['data']
            True
        
        
        
        gocept.webtoken
        ===============
        
        3.1.post1 (2020-04-08)
        ----------------------
        
        - Drop faulty ``python_requires`` in `setup.py`.
        
        
        3.1 (2020-04-08)
        ----------------
        
        - Migrate to Github.
        
        - Test with Python 3.8 and PyPy3.
        
        - Stop testing with Python 3.5.
        
        3.0 (2018-11-14)
        ----------------
        
        - Change license from ZPL to MIT.
        
        - Add support for Python 3.7.
        
        - Drop support for Python 3.4.
        
        - Make subject check optional as some systems like Keycloak use a random
          uuid as the subject which is unknown for the decoder.
        
        - Add `audience` parameter which is required to decode tokens generated
          by Keycloak.
        
        
        2.0 (2018-01-08)
        ----------------
        
        - Drop support for Python 3.3 but add it for 3.6.
        
        - Make `setup.py` compatible with newer `setuptools` versions by no longer
          using absolute paths.
        
        
        1.2.1 (2015-10-08)
        ------------------
        
        - Fix `extract_token` to accept any ``collections.Mapping`` derived object.
        
        
        1.2 (2015-10-08)
        ----------------
        
        - Added helper functions to create a Bearer Authorization header and extract
          a token from it.
        
        - Officially support Python 3.5.
        
        
        1.1 (2015-10-01)
        ----------------
        
        - Shortened imports for `CryptographicKeys`, `create_web_token` and
          `decode_web_token`, which are now importable directly from `gocept.webtoken`.
        
        - Added documentation.
        
        
        1.0 (2015-10-01)
        ----------------
        
        * Add support for Python 3.3 and 3.4.
        
        * Initial release, extracted from internally used package.
        
Keywords: jwt token webtoken ZCA
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Security
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
