djangorestframework-simplejwt 1.2

Discourage crypto negotiation

Protocols which allow for negotiation of crypto algorithms (this includes JWT) are generally considered to be weak by design. Simple JWT assumes that most use cases will be covered by sha-256 HMAC signing with a shared secret. Customization of which algorithms are used to sign/verify tokens is possible but not intended to be easy.

Object oriented API

The implementation of Simple JWT emphasizes an object-oriented design. The intention is that customization of Simple JWT’s funcionality is done mostly through subclassing. This will hopefully encourage developers to understand the library at a deeper level and possibly reduce the risk of deploying a flawed JWT authentication system. The classes which comprise the bulk of Simple JWT’s functionality are meant to be easy to read and understand.

Safe defaults

Configurable aspects of Simple JWT should have reasonably safe defaults. Users of this library should feel free to plug and play without shooting themselves in the foot.

Installation

Simple JWT can be installed with pip:

pip install djangorestframework_simplejwt

Then, your django project must be configured to use the library. In settings.py, add rest_framework_simplejwt.authentication.JWTAuthentication to the list of authentication classes:

REST_FRAMEWORK = {
    ...
    'DEFAULT_AUTHENTICATION_CLASSES': (
        ...
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    )
    ...
}

Also, in your root urls.py file, include Simple JWT’s default urls:

urlpatterns = [
    ...
    url(r'^api/', include('rest_framework_simplejwt.urls')),
    ...
]

API views to obtain and refresh tokens should be available at /api/token/obtain/ and /api/token/refresh/.

Usage

To verify that Simple JWT is working, you can use curl to issue a couple of test requests:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "davidattenborough", "password": "boatymcboatface"}' \
  http://localhost:8000/api/token/obtain/

...
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3BrIjoxLCJjb2xkX3N0dWZmIjoi4piDIiwiZXhwIjoxMjM0NTYsInJlZnJlc2hfZXhwIjoxMjM1MDB9.8po9BafZiPi1aaWTKYCt3q0_2eLlWabj4nfQVYXLCK8"}

You can use the returned token to prove authentication for a protected view:

curl \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3BrIjoxLCJjb2xkX3N0dWZmIjoi4piDIiwiZXhwIjoxMjM0NTYsInJlZnJlc2hfZXhwIjoxMjM1MDB9.8po9BafZiPi1aaWTKYCt3q0_2eLlWabj4nfQVYXLCK8" \
  http://localhost:8000/api/some-protected-view/

Or you can refresh the token if it is still refreshable:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3BrIjoxLCJjb2xkX3N0dWZmIjoi4piDIiwiZXhwIjoxMjM0NTYsInJlZnJlc2hfZXhwIjoxMjM1MDB9.8po9BafZiPi1aaWTKYCt3q0_2eLlWabj4nfQVYXLCK8"}' \
  http://localhost:8000/api/token/refresh/

...
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX3BrIjoxLCJjb2xkX3N0dWZmIjoi4piDIiwiZXhwIjoxMjM0ODAsInJlZnJlc2hfZXhwIjoxMjM1MDB9.tTXYxsumgb7Odj9NsAAVpSaNnkS8gfAh-yjEnlW0JiQ"}

Settings

Some of Simple JWT’s behavior can be customized through settings variables in settings.py:

from datetime import timedelta

...

SIMPLE_JWT = {
    'AUTH_HEADER_TYPE': 'Bearer',

    'USER_ID_FIELD': 'id',
    'PAYLOAD_ID_FIELD': 'user_id',

    'TOKEN_LIFETIME': timedelta(days=1),
    'TOKEN_REFRESH_LIFETIME': timedelta(days=7),

    'SECRET_KEY': SECRET_KEY,  # Default to the django secret key

    'TOKEN_BACKEND': 'rest_framework_simplejwt.backends.TokenBackend',
}

Above, the default values for these settings are shown.

AUTH_HEADER_TYPE

The authorization header type that will be checked for views that require authentication. For example, a value of 'Bearer' means that views requiring authentication would look for a header with the following format: Authorization: Bearer <token>.

USER_ID_FIELD

The database field from the user model that will be included in generated tokens to identify users. It is recommended that the value of this setting specifies a field which does not normally change once its initial value is chosen. For example, specifying a “username” or “email” field would be a poor choice since an account’s username or email might change depending on how account management in a given service is designed. This could allow a new account to be created with an old username while an existing token is still valid which uses that username as a user identifier.

PAYLOAD_ID_FIELD

The key name which will be used for the claim that specifies the user identifier in generated tokens. For example, a setting value of 'user_id' would mean generated tokens include a “user_id” claim that contains the user’s identifier.

TOKEN_LIFETIME

A datetime.timedelta object which specifies how long a generated token is valid. This timedelta value is added to the current UTC time while a token is being generated to obtain the token’s “exp” claim value. Once the time specified by this “exp” claim has passed, a token will no longer be valid for authorization and can no longer be refreshed.

TOKEN_REFRESH_LIFETIME

A datetime.timedelta object which specifies how long a generated token may be refreshed. This timedelta value is added to the current UTC time while a token is being generated to obtain the token’s “refresh_exp” claim value. Once the time specified by this “refresh_exp” claim has passed, a token can no longer be refreshed. However, if the time specified by a token’s “exp” claim still has not passed, it can still be used for authorization.

SECRET_KEY

The secret key which is used to sign the content of generated tokens. This setting defaults to the value of the SECRET_KEY setting for the django project. Although this is the most reasonable default that Simple JWT can provide, it is recommended that developers change this setting to a value which is independent from the django project secret key. This will make changing the secret key used for tokens easier in the event that it is compromised or a token exists which must be immediately invalidated.

TOKEN_BACKEND

Specifies a dot path to a class which implements a set of low-level token operations used by Simple JWT. For more information, see the “Customization” section below.