JWT Auth¶

Docs: https://jwt.io

Important

To use jwt you must install 'django-modern-rest[jwt]' extra.

Requiring auth¶

Note

Current user will always be accessible as self.request.user.

We provide two classes to require JWT auth in your API:

JWTSyncAuth for sync views
JWTAsyncAuth for async views

Example, how to use the auth class and how to get self.request.user:

views.py¶

[source]

from django.contrib.auth.models import User

from dmr import Controller
from dmr.plugins.pydantic import PydanticSerializer
from dmr.security import AuthenticatedHttpRequest
from dmr.security.jwt import JWTSyncAuth


class APIController(Controller[PydanticSerializer]):
    request: AuthenticatedHttpRequest[User]
    auth = (JWTSyncAuth(),)

    def get(self) -> str:
        # Let's test that `User` has the correct type:
        assert self.request.user.username
        return 'authed'

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      }
    },
    "securitySchemes": {
      "jwt": {
        "bearerFormat": "JWT",
        "description": "JWT token auth",
        "scheme": "Bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/apicontroller/": {
      "get": {
        "deprecated": false,
        "operationId": "getApicontrollerApiApicontroller",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when auth was not successful"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        },
        "security": [
          {
            "jwt": []
          }
        ]
      }
    }
  }
}

Reusing pre-existing views¶

We provide several pre-existing views to get auth tokens. So, users won’t have to write tons of boilerplate code.

JWT with access and refresh tokens¶

We provide two Reusable controllers to obtain pairs of access and refresh tokens:

ObtainTokensSyncController for sync controllers
ObtainTokensAsyncController for async controllers

To use them, you will need to:

Provide actual types for serializer, request model, and response body
Redefine convert_auth_payload() to convert your request model into the kwargs of django.contrib.auth.authenticate() to authenticate your request
Redefine make_api_response() to return the response in the format of your choice

views.py¶

[source]

import datetime as dt

from typing_extensions import override

from dmr.plugins.pydantic import PydanticSerializer
from dmr.security.jwt.views import (
    ObtainTokensPayload,
    ObtainTokensResponse,
    ObtainTokensSyncController,
)


# You can also use `ObtainTokensAsyncController` if needed:
class ObtainAccessAndRefreshSyncController(
    ObtainTokensSyncController[
        PydanticSerializer,
        ObtainTokensPayload,
        ObtainTokensResponse,
    ],
):
    @override
    def convert_auth_payload(
        self,
        payload: ObtainTokensPayload,
    ) -> ObtainTokensPayload:
        return payload

    @override
    def make_api_response(self) -> ObtainTokensResponse:
        now = dt.datetime.now(dt.UTC)
        return {
            'access_token': self.create_jwt_token(
                expiration=now + self.jwt_expiration,
                token_type='access',
            ),
            'refresh_token': self.create_jwt_token(
                expiration=now + self.jwt_refresh_expiration,
                token_type='refresh',
            ),
        }

Run result

$ curl http://127.0.0.1:8000/api/auth/ -X POST -d '{"username": "test_user", "password": "password"}' -H 'Content-Type: application/json'
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiZXhwIjoxNzc4MjQ1MDM5LCJpYXQiOjE3NzgxNTg2MzksImp0aSI6IjEyNzgwMGZhNjRmNzQzOWU5NTU5NDFiOGZkYWY4NzIyIiwiZXh0cmFzIjp7InR5cGUiOiJhY2Nlc3MifX0._z4LjN9QR1oyiQeMHnFVdeR8Fcj1FdfhKYQXHSxe3LI","refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiZXhwIjoxNzc5MDIyNjM5LCJpYXQiOjE3NzgxNTg2MzksImp0aSI6Ijc4MTdjY2Y5MGI2ZjQ2ZDU4OGI4MGExMjQ0NWFmMTdhIiwiZXh0cmFzIjp7InR5cGUiOiJyZWZyZXNoIn19.oTv1oJIlPB0erNkXFIJI7pSiz99dlndi1sCPb5lU_i4"}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "ObtainTokensPayload": {
        "description": "Payload for default version of a jwt request body.\n\nIs also used as kwargs for :func:`django.contrib.auth.authenticate`.",
        "properties": {
          "password": {
            "title": "Password",
            "type": "string"
          },
          "username": {
            "title": "Username",
            "type": "string"
          }
        },
        "required": [
          "username",
          "password"
        ],
        "title": "ObtainTokensPayload",
        "type": "object"
      },
      "ObtainTokensResponse": {
        "description": "Default response type for refresh token endpoint.",
        "properties": {
          "access_token": {
            "title": "Access Token",
            "type": "string"
          },
          "refresh_token": {
            "title": "Refresh Token",
            "type": "string"
          }
        },
        "required": [
          "access_token",
          "refresh_token"
        ],
        "title": "ObtainTokensResponse",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/obtainaccessandrefreshsynccontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postObtainaccessandrefreshsynccontrollerApiObtainaccessandrefreshsynccontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ObtainTokensPayload"
              }
            }
          },
          "description": "Payload for default version of a jwt request body.\n\nIs also used as kwargs for :func:`django.contrib.auth.authenticate`.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ObtainTokensResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Unauthorized"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        },
        "summary": "By default tokens are acquired on post."
      }
    }
  }
}

In this example we utilize pre-defined types of request model and response body, only doing the bare minimum with no customizations.

Things that you can customize:

Request body format
Response body format
JWT settings
JWT token class to be JWToken subclass with custom logic
Error messages, see Customizing error messages
Error handling, see Error handling
Response status code and any other regular controller or endpoint features

Here’s an example with a lot more customizations:

views.py¶

[source]

import datetime as dt

from typing_extensions import TypedDict, override

from dmr.plugins.pydantic import PydanticSerializer
from dmr.security.jwt.views import (
    ObtainTokensPayload,
    ObtainTokensSyncController,
)


# Custom request and response models:
class _RequestModel(TypedDict):
    email: str
    password: str


class _TokensModel(TypedDict):
    access: str
    refresh: str


class _ResponseModel(TypedDict):
    auth: _TokensModel


# You can also use `ObtainTokensAsyncController` if needed:
class ObtainAccessAndRefreshSyncController(
    ObtainTokensSyncController[
        PydanticSerializer,
        _RequestModel,
        _ResponseModel,
    ],
):
    # Customizes the default jwt settings:
    jwt_issuer = 'my-awesome-company'
    jwt_algorithm = 'HS512'
    jwt_audiences = ('dev', 'qa')

    @override
    def convert_auth_payload(
        self,
        payload: _RequestModel,
    ) -> ObtainTokensPayload:
        return {'username': payload['email'], 'password': payload['password']}

    @override
    def make_api_response(self) -> _ResponseModel:
        now = dt.datetime.now(dt.UTC)
        access = self.create_jwt_token(
            expiration=now + self.jwt_expiration,
            token_type='access',
        )
        refresh = self.create_jwt_token(
            expiration=now + self.jwt_refresh_expiration,
            token_type='refresh',
        )
        return {
            'auth': {
                'access': access,
                'refresh': refresh,
            },
        }

Run result

$ curl http://127.0.0.1:8000/api/auth/ -X POST -d '{"email": "test_user", "password": "password"}' -H 'Content-Type: application/json'
{"auth":{"access":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiZXhwIjoxNzc4MjQ1MDQwLCJpYXQiOjE3NzgxNTg2NDAsImlzcyI6Im15LWF3ZXNvbWUtY29tcGFueSIsImF1ZCI6WyJkZXYiLCJxYSJdLCJqdGkiOiJlOWQ3YjBkZjg2ZDA0OWY4YTk0Yjk4YWZiMTJmYmI2MiIsImV4dHJhcyI6eyJ0eXBlIjoiYWNjZXNzIn19.lcveBSyiyJnc_QaYm-WmcJFvyJaAsBh0rQpw_u82wMSCm2fbZ3N2qhUWUGPoZlac6-CF7OHBJ7-9C_kU4-5c_w","refresh":"eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxIiwiZXhwIjoxNzc5MDIyNjQwLCJpYXQiOjE3NzgxNTg2NDAsImlzcyI6Im15LWF3ZXNvbWUtY29tcGFueSIsImF1ZCI6WyJkZXYiLCJxYSJdLCJqdGkiOiJjZGFjYWM4Nzk4OWQ0ZTg3OGExMWMxNTNmODFmMjBlNiIsImV4dHJhcyI6eyJ0eXBlIjoicmVmcmVzaCJ9fQ.DRBjkCwgqhpfO-W0WBLv54EKt59GvwlHL4IwlfjHFOHT-RzI6se7EWrO0rITol9BNczVE3sHJsgRRgsSy-pDNw"}}

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "_RequestModel": {
        "properties": {
          "email": {
            "title": "Email",
            "type": "string"
          },
          "password": {
            "title": "Password",
            "type": "string"
          }
        },
        "required": [
          "email",
          "password"
        ],
        "title": "_RequestModel",
        "type": "object"
      },
      "_ResponseModel": {
        "properties": {
          "auth": {
            "$ref": "#/components/schemas/_TokensModel"
          }
        },
        "required": [
          "auth"
        ],
        "title": "_ResponseModel",
        "type": "object"
      },
      "_TokensModel": {
        "properties": {
          "access": {
            "title": "Access",
            "type": "string"
          },
          "refresh": {
            "title": "Refresh",
            "type": "string"
          }
        },
        "required": [
          "access",
          "refresh"
        ],
        "title": "_TokensModel",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/obtainaccessandrefreshsynccontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postObtainaccessandrefreshsynccontrollerApiObtainaccessandrefreshsynccontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/_RequestModel"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/_ResponseModel"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Unauthorized"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        },
        "summary": "By default tokens are acquired on post."
      }
    }
  }
}

This example also provides issuer and audience in the token, so it can be used together with accepted_issuers and accepted_audiences configurations of dmr.security.jwt.auth.JWTSyncAuth to additionally validate aud and iss JWT token claims.

We want to be sure that this class is at the same time:

Easy enough to not write a lot of boilerplate code by default
Customizable enough to be able to change a lot of stuff that can be affected by existing business rules
Always type safe

Refreshing tokens¶

Once a user has a refresh token, they can use it to obtain a new pair of access and refresh tokens without re-authenticating. We provide two Reusable controllers for this:

RefreshTokenSyncController for sync controllers
RefreshTokenAsyncController for async controllers

To use them, you only need to:

Provide actual types for serializer, request payload, and response body
Redefine convert_refresh_payload() to extract the refresh token string from your request payload
Redefine make_api_response() to return the new token pair in the format of your choice

The controller validates that the submitted token:

Is a valid, non-expired JWT signed with the configured secret
Has extras.type == 'refresh' (i.e. it is a refresh token, not an access token)
Belongs to an existing, active user

views.py¶

[source]

import datetime as dt

from typing_extensions import override

from dmr.plugins.pydantic import PydanticSerializer
from dmr.security.jwt.views import (
    ObtainTokensResponse,
    RefreshTokenPayload,
    RefreshTokenSyncController,
)


# You can also use `RefreshTokenAsyncController` if needed:
class RefreshSyncController(
    RefreshTokenSyncController[
        PydanticSerializer,
        RefreshTokenPayload,
        ObtainTokensResponse,
    ],
):
    @override
    def convert_refresh_payload(self, payload: RefreshTokenPayload) -> str:
        return payload['refresh_token']

    @override
    def make_api_response(self) -> ObtainTokensResponse:
        now = dt.datetime.now(dt.UTC)
        return {
            'access_token': self.create_jwt_token(
                expiration=now + self.jwt_expiration,
                token_type='access',
            ),
            'refresh_token': self.create_jwt_token(
                expiration=now + self.jwt_refresh_expiration,
                token_type='refresh',
            ),
        }

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      },
      "ObtainTokensResponse": {
        "description": "Default response type for refresh token endpoint.",
        "properties": {
          "access_token": {
            "title": "Access Token",
            "type": "string"
          },
          "refresh_token": {
            "title": "Refresh Token",
            "type": "string"
          }
        },
        "required": [
          "access_token",
          "refresh_token"
        ],
        "title": "ObtainTokensResponse",
        "type": "object"
      },
      "RefreshTokenPayload": {
        "description": "Default request body type for the refresh token endpoint.",
        "properties": {
          "refresh_token": {
            "title": "Refresh Token",
            "type": "string"
          }
        },
        "required": [
          "refresh_token"
        ],
        "title": "RefreshTokenPayload",
        "type": "object"
      }
    },
    "securitySchemes": {}
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/refreshsynccontroller/": {
      "post": {
        "deprecated": false,
        "operationId": "postRefreshsynccontrollerApiRefreshsynccontroller",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshTokenPayload"
              }
            }
          },
          "description": "Default request body type for the refresh token endpoint.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ObtainTokensResponse"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when request components cannot be parsed"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Unauthorized"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        },
        "summary": "Refresh tokens on POST."
      }
    }
  }
}

Blocklisting tokens¶

Note

Add 'dmr.security.jwt.blocklist' to the INSTALLED_APPS if you want to use tokens blocklist.

JWT tokens might be leaked / outdated / etc. There must be a way to make a valid, non-expired token blocked from auth.

To do so, we provide a default Django app to do so. We store blocked tokens in the database and provide an API to add tokens to the blocklist.

Here’s an example:

views.py¶

[source]

from django.contrib.auth.models import User

from dmr import Controller
from dmr.plugins.pydantic import PydanticSerializer
from dmr.security import AuthenticatedHttpRequest, request_auth
from dmr.security.jwt import JWTAsyncAuth, request_jwt
from dmr.security.jwt.blocklist import JWTokenBlocklistAsyncMixin


class JWTAuthWithBlocklist(JWTokenBlocklistAsyncMixin, JWTAsyncAuth):
    """This class will also check that tokens are not blocklisted."""


jwt_blocklist_auth = JWTAuthWithBlocklist()


class APIController(Controller[PydanticSerializer]):
    request: AuthenticatedHttpRequest[User]
    auth = (jwt_blocklist_auth,)

    async def get(self) -> str:
        # Disable tokens for users with old domain emails
        if self.request.user.email.endswith('@old-domain.com'):
            assert request_auth(self.request) is jwt_blocklist_auth
            await jwt_blocklist_auth.blocklist(
                request_jwt(self.request, strict=True),
            )
        return 'authed'

OpenAPI Schema

Preview openapi.json

{
  "components": {
    "schemas": {
      "ErrorDetail": {
        "description": "Base schema for error details description.",
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "msg"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorModel": {
        "description": "Default error response schema.\n\nCan be customized.\nSee :ref:`customizing-error-messages` for more details.",
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ErrorDetail"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "required": [
          "detail"
        ],
        "title": "ErrorModel",
        "type": "object"
      }
    },
    "securitySchemes": {
      "jwt": {
        "bearerFormat": "JWT",
        "description": "JWT token auth",
        "scheme": "Bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "title": "Django Modern Rest",
    "version": "0.1.0"
  },
  "openapi": "3.2.0",
  "paths": {
    "/api/apicontroller/": {
      "get": {
        "deprecated": false,
        "operationId": "getApicontrollerApiApicontroller",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "OK"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when auth was not successful"
          },
          "406": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when provided `Accept` header cannot be satisfied"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorModel"
                }
              }
            },
            "description": "Raised when returned response does not match the response schema"
          }
        },
        "security": [
          {
            "jwt": []
          }
        ]
      }
    }
  }
}

We provide two mixin types:

JWTokenBlocklistAsyncMixin for async auth
JWTokenBlocklistSyncMixin for sync auth

API Reference¶

class dmr.security.jwt.token.JWToken(sub: str, exp: datetime, iat: datetime = <factory>, iss: str | None = None, aud: str | Sequence[str] | None = None, jti: str | None = None, extras: dict[str, ~typing.Any]=<factory>, leeway: dataclasses.InitVar[int] = 0)[source]¶

JWT Token DTO.

sub¶

Subject - usually a unique identifier of the user or equivalent entity.

Type:: str

exp¶

Expiration - datetime for token expiration.

Type:: datetime.datetime

iat¶

Issued at - should always be current now.

Type:: datetime.datetime

iss¶

Issuer - optional unique identifier for the issuer.

Type:: str | None

aud¶

Audience - intended audience(s).

Type:: str | collections.abc.Sequence[str] | None

jti¶

JWT ID - a unique identifier of the JWT between different issuers.

Type:: str | None

extras¶

Extra fields that were found on the JWT token.

Type:: dict[str, Any]

__post_init__(leeway: int) → None[source]¶: Runs extra validation.

classmethod decode(encoded_token: str, secret: str, algorithm: str, *, leeway: int = 0, accepted_audiences: str | Sequence[str] | None = None, accepted_issuers: str | Sequence[str] | None = None, require_claims: Sequence[str] | None = None, verify_exp: bool = True, verify_iat: bool = True, verify_jti: bool = True, verify_nbf: bool = True, verify_sub: bool = True, strict_audience: bool = False, enforce_minimum_key_length: bool = True) → Self[source]¶

Decode a passed in token string and return a Token instance.

Parameters:

encoded_token – A base64 string containing an encoded JWT.
secret – The secret with which the JWT is encoded.
algorithm – The algorithm used to encode the JWT.
leeway – Number of potential seconds as a clock error for expired tokens.
accepted_audiences – Verify the audience when decoding the token.
accepted_issuers – Verify the issuer when decoding the token.
require_claims – Verify that the given claims are present in the token.
verify_exp – Verify that the value of the exp (expiration) claim is in the future.
verify_iat – Verify that iat (issued at) claim value is an integer.
verify_jti – Check that jti (JWT ID) claim is a string.
verify_nbf – Verify that the value of the nbf (not before) claim is in the past.
verify_sub – Check that sub (subject) claim is a string.
strict_audience – Verify that the value of the aud (audience) claim is a single value, and not a list of values, and matches audience exactly. Requires the value passed to the audience to be a sequence of length 1.
enforce_minimum_key_length – Raise an auth error when keys are below minimum recommended length.

Returns:

A decoded Token instance.

Raises:

NotAuthenticatedError – If the token is invalid.

Pre-defined views to fetch JWT tokens¶

class dmr.security.jwt.views.ObtainTokensSyncController(**kwargs)[source]¶

Sync controller to get access and refresh tokens.

jwt_audiences¶

String or sequence of string of audiences for JWT token.

Type:: ClassVar[str | collections.abc.Sequence[str] | None]

jwt_issuer¶

String of who issued this JWT token.

Type:: ClassVar[str | None]

jwt_algorithm¶

Default algorithm to use for token signing.

Type:: ClassVar[str]

jwt_expiration¶

Default access token expiration timedelta.

Type:: ClassVar[datetime.timedelta]

jwt_refresh_expiration¶

Default refresh token expiration timedelta.

Type:: ClassVar[datetime.timedelta]

jwt_secret¶

Alternative token secret for signing. By default uses secret.SECRET_KEY

Type:: ClassVar[str | None]

jwt_token_cls¶

Possible custom JWT token class.

Type:: ClassVar[type[dmr.security.jwt.token.JWToken]]

Blocklist app¶

class dmr.security.jwt.blocklist.auth.JWTokenBlocklistSyncMixin[source]¶

Sync mixin for working with tokens blocklist.

blocklist(token: JWToken) → tuple[BlocklistedJWToken, bool][source]¶: Add token to the blocklist.

check_auth(user: AbstractBaseUser, token: JWToken) → None[source]¶: Check if the token is in the black list, if so raise the error.

class dmr.security.jwt.blocklist.auth.JWTokenBlocklistAsyncMixin[source]¶

Async mixin for working with tokens blocklist.

async blocklist(token: JWToken) → tuple[BlocklistedJWToken, bool][source]¶: Add token to the blocklist.

async check_auth(user: AbstractBaseUser, token: JWToken) → None[source]¶: Check if the token is in the black list, if so raise the error.