ayys / knoxth

Knoxth uses Knox tokens to provide token-level authorization management for DRF viewsets.

Knoxth - Auth for Knox

A authorization module for django built on top of DRF and Knox.

Introduction • Installation • How To Use • Documentation • License

Introduction

Knoxth uses Knox tokens to provide token-level authorization management for DRF viewsets.

Django Rest Frameowork is an amazingly simple to use and easy frameowork to write REST APIs in Django. With Knox, you can secure your API with Access Tokens. Yet, there is a gap left by Knox, the need for context-specific authentication system built on top of knox.

Users will want to customize the "scope" of each token they create. This way, users may create different tokens for separate usecases.

Let's take an example. Let us say you are developinga rest api that lets it's create and manage TODO lists. Now, you have a viewset that handles all CRUD operations, but you want to provide a way for users to manage access to their todo lists on a token level. So, a user may want to create a token, with which they can only read TODO lists, but not modify them.

This is where knoxth comes in. Knoxth implements contextual authorization of DRF viewsets on token level, using Knox Tokens.

Installation

Knox should be installed with pip

1. Install knoxth

pip install knoxth

For pipenv projects, it can also be installed as such

pipenv install knoxth

After installing knoxth, you will need to setup knoxth to work with your existing project. Before seting up knoxth, make sure you have rest_framework and knox setup and ready to go.

2. Add to INSTALLED_APPS

Add rest_framework, knox and knoxth to your INSTALLED_APPS, and add rest_framework.authtoken if you removed it while setting up knox.

INSTALLED_APPS = (
  ...
  'rest_framework',
  'rest_framework.authtoken',
  'knox',
  'knoxth',
  ...
)

3. Setup default Authentication class

Make knox's TokenAuthentication your default authentication class for django-rest-framework:

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': ('knox.auth.TokenAuthentication',),
    ...
}

4. Include knoxth URLS

Knoxth provides a url config ready with its four default views routed.

This can easily be included in your url config:

urlpatterns = [
  #...snip...
  url(r'api/auth/', include('knoxth.urls'))
  #...snip...
]

Note It is important to use the string syntax and not try to import knoxth.urls, as the reference to the User model will cause the app to fail at import time.

The views would then acessible as:

Endpoint	Description
/api/auth/authorize	Authorize username & password. Return authorization code.
/api/auth/login	Accept authorization code and return access token
/api/auth/logout	Logout the user and delete the access token and authorization code.
/api/auth/logoutall	Same as logout, but logs out of all running sessions.

they can also be looked up by name:

reverse('knoxth_login')
reverse('knoxth_logout')
reverse('knoxth_logoutall')
reverse('knoxth_authorize')

5. Migrate

Apply the migrations for the models

python manage.py migrate

How To Use

Refer to our documentation for details, or follow our getting started guide.

License

GNU GPL V3

---

GitHub @ayys  ·  Twitter @habuayush

knoxth's Issues

Refactor the project for better testing

The current project cannot be tested properly because it is not a valid Django project.
By turning it into a Django project, we can write tests easily.

Documentaiton: Complete the Getting Started docs

Explain Context, Scope and Claim in documentation