Metadata-Version: 1.1
Name: drf-tmp-scoped-token
Version: 0.2.1
Summary: Temporary Django REST Framework permission-scoped token
Home-page: https://github.com/Cadasta/drf-tmp-scoped-token
Author: Anthony Lukach
Author-email: alukach@cadasta.org
License: GNU Affero General Public License v3.0
Description: DRF Temporary Scoped Token
        ==========================
        
        |Build Status| |Requirements Status|
        
        ``rest_framework_tmp_scoped_token`` provides a Django REST
        Framework-compatible system to generate and validate signed
        authorization tokens. Generated tokens contain the ID of a user on whose
        behalf the token bearer authenticates, a white-list of HTTP verbs and
        API endpoints that the bearer is permitted to access, an max-lifespan of
        the token, and a note about the intended recipient.
        
        Usage
        -----
        
        Authorization
        ~~~~~~~~~~~~~
        
        Add ``rest_framework_tmp_scoped_token.TokenAuth`` to the
        ``DEFAULT_AUTHENTICATION_CLASSES`` section of your ``REST_FRAMEWORK``
        settings in ``settings.py``:
        
        .. code:: python
        
            REST_FRAMEWORK = {
                'DEFAULT_AUTHENTICATION_CLASSES': (
                    # ... Your other forms of auth
                    'rest_framework_tmp_scoped_token.TokenAuth',
                )
            }
        
        To authenticate with an temporary permissions token, make a request with
        the token included in either:
        
        -  the ``Authorization`` HTTP header with a ``TmpToken`` keyword:
        
           .. code:: http
        
               Authorization: TmpToken eyJzb21ldGhpbmctc2VjcmV0IjoiaG9wZSBub2JvZHkgc2VlcyB0aGlzIn0:1d47N6:woJG0EgLNDb0OjYQmCbsjniP-2Y
        
        -  a ``TOKEN`` ``GET`` query parameter:
        
           .. code:: http
        
               /api/?TOKEN=eyJzb21ldGhpbmctc2VjcmV0IjoiaG9wZSBub2JvZHkgc2VlcyB0aGlzIn0:1d47N6:woJG0EgLNDb0OjYQmCbsjniP-2Y
        
        If you would like to customize either the ``Authorization`` header
        keyword or the ``GET`` query parameter used, you can subclass the
        ``rest_framework_tmp_scoped_token.TokenAuth`` class and override the
        ``keyword`` or ``get_param`` values.
        
        Token
        ~~~~~
        
        To generate a token, use the
        ``rest_framework_tmp_scoped_token.TokenManager`` class. The token
        encompasses the following information:
        
        -  **user**: User that will be authenticated by token.
        -  **endpoints**: key:value pairs of HTTP methods and endpoint roots
           that token is authorized to access. The following values would
           authorize the token to make GET requests to any endpoints that begin
           with '``api/v1/foo``:
        
           .. code:: python
        
               {'GET': ['/api/v1/foo']}
        
           **NOTE**: This this token will not override any existing permissions
           for its associatted User within the system. It only adds further
           restrictions to the endpoints that can be accessed.
        -  **max\_age**: How long, in seconds, the token will be valid. By
           default, tokens will be valid for 1 hour. Non-expiring tokens are not
           supported.
        -  **recipient**: *(Optional)* A textual description of the recipient
           for which this token was intended. No validation is done with this
           data, however it is appended to the request as a
           ``X-API-Token-Recipient`` header by the accompanying DRF
           authentication scheme. This is for tracking purposes
        
        **NOTE**: The tokens are signed via Django's
        ```signing`` <https://docs.djangoproject.com/en/dev/topics/signing/>`__
        facility. It is important to know that the **tokens are not encrypted**,
        they are simply signed. For this reason, you should not include any
        sensitive/secret information in the tokens. For an example, notice how
        easy it is to view the contents of a signed string:
        
        .. code:: python
        
            In [1]: from django.core import signing
        
            In [2]: t = signing.dumps({'something-secret': 'hope nobody sees this'})
        
            In [3]: print(t)
            eyJzb21ldGhpbmctc2VjcmV0IjoiaG9wZSBub2JvZHkgc2VlcyB0aGlzIn0:1d47N6:woJG0EgLNDb0OjYQmCbsjniP-2Y
        
            In [4]: import base64
        
            In [5]: print(base64.urlsafe_b64decode(t.encode('utf8')))
            b'{"something-secret":"hope nobody sees this"}5w\x8e\xcd\xeb\n\t\x1bA ,\xd0\xdb\xd0\xe8\xd8B`\x9b\xb29\xe2?\xed\x98'
        
        Contributing
        ------------
        
        Testing
        ~~~~~~~
        
        .. code:: bash
        
            pip install -r requirements-test.txt
            ./runtests
        
        Deploying
        ~~~~~~~~~
        
        .. code:: bash
        
            pip install -r requirements-deploy.txt
            python setup.py test clean build tag publish
        
        .. |Build Status| image:: https://travis-ci.org/Cadasta/drf-tmp-scoped-token.svg?branch=master
           :target: https://travis-ci.org/Cadasta/drf-tmp-scoped-token
        .. |Requirements Status| image:: https://requires.io/github/Cadasta/drf-tmp-scoped-token/requirements.svg?branch=master
           :target: https://requires.io/github/Cadasta/drf-tmp-scoped-token/requirements/?branch=master
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
