django-rest-knox Documentation

django-rest-knox is an authentication module for Django REST Framework (DRF) that provides token-based authentication. It improves upon DRF's built-in TokenAuthentication in three key ways:

1. Multiple Tokens per User: Unlike DRF, which limits users to one token, Knox allows each device/client to have its own unique token. This enables individual device logout and the ability to revoke all tokens for a user simultaneously.
2. Secure Token Storage: Knox stores tokens as secure hashes (similar to passwords) rather than unencrypted strings. This protects accounts even if the database is compromised.
3. Token Expiration: Knox supports configurable token expiration, whereas DRF tokens do not have an inbuilt expiration mechanism. By default, tokens expire after 10 hours.

Django-Rest-Knox is a token-based authentication library for Django REST Framework (DRF). It improves upon DRF's built-in TokenAuthentication in three key areas:

1. Multi-device support: Unlike DRF, which is limited to one token per user, Knox provides a unique token for every login call. This allows multiple devices to be logged in simultaneously and enables individual device logout without affecting others. It also includes settings to limit the total number of tokens per user.
2. Security (Encryption): DRF tokens are stored unencrypted in the database. Knox tokens are stored in an encrypted form, protecting user accounts even if the database is compromised.
3. Token Expiration: While DRF tokens do not expire by default, Knox allows you to configure a token expiry time in your application settings (the default is 10 hours).

Install the Knox package using pip to add it to your Python environment.

pip install django-rest-knox

The project documentation is generated using Mkdocs. You can run the documentation locally using the provided mkdocs.sh script, which runs Mkdocs inside a Docker container.

Running the documentation server

Running the script without parameters triggers the serve command, exposing the documentation on localhost:8000.

To change the port, set the MKDOCS_DEV_PORT environment variable.

Passing Mkdocs commands

You can pass standard mkdocs commands directly to the script (e.g., build or --help).

To set up Knox in your Django project, follow these steps:

1. Update INSTALLED_APPS: Add 'rest_framework' and 'knox' to your INSTALLED_APPS. If you were previously using rest_framework.authtoken, remove it.
2. Set Default Authentication: Configure Django Rest Framework to use Knox's TokenAuthentication as the default authentication class.
3. Add URL Patterns: Include the Knox URL patterns in your project's urls.py.
4. Run Migrations: Apply the database migrations for the Knox models.

# INSTALLED_APPS configuration
INSTALLED_APPS = (
  ...
  'rest_framework',
  'knox',
  ...
)

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

To run the test suite across all supported Python and Django versions using Docker, execute the provided shell script. This is useful for debugging tests locally without manually managing multiple environments.

Alternatively, you can run tox in the root folder, though managing the version matrix is more manual.

./docker-run-tests.sh

After configuring your settings and adding the Knox URL patterns, run the Django migration command to create the necessary database tables for Knox.

python manage.py migrate

Knox provides a pre-configured URL pattern containing its three default views. To include them in your project, add include('knox.urls') to your urlpatterns.

CRITICAL: You must use the string syntax (e.g., 'knox.urls') rather than importing the module directly. Importing knox.urls will cause an import-time failure because the module references the User model.

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

Knox provides TokenAuthentication to integrate with Django REST Framework's authentication system. To protect an APIView or ViewSet, add TokenAuthentication to the authentication_classes attribute.

To authenticate requests, include an Authorization header with the value Token <your_token_string>. Tokens are generated via Knox's provided views (e.g., LoginView).

from rest_framework.permissions import IsAuthenticated
from rest_framework.response import Response
from rest_framework.views import APIView

from knox.auth import TokenAuthentication

class ExampleView(APIView):
    authentication_classes = (TokenAuthentication,)
    permission_classes = (IsAuthenticated,)

    def get(self, request, format=None):
        content = {
            'foo': 'bar'
        }
        return Response(content)