Skip to main content

django-rest-microservice

This package is built on the djangorestframework-simplejwt package, which provides some JWT authentication mechanisms with Django REST framework. This package offers the following features:

  • Provides refresh cookie in HttpOnly cookie, and access token in response body, for better security when implemented properly with SPA.
  • Provides an easier approach to customizing token claims than the standard mechanism described in djangorestframework-simplejwt documentation.
  • Provides a mechanism for authentication with a third-party IDP, before issuing internal JWT to your users.
  • Currently, supports authentication with AWS Cognito using OAuth 2 Code Grant with PKCE for best security practices.

Installation

Install package to environment:

pip install django-rest-microservice

In the main urls.py, include the default package url routes:

from django.urls import path, include

urlpatterns = [
    path("auth/", include("rest_framework_microservice.urls"))
]

In Django settings, include the following:

INSTALLED_APPS = [
    ...,
    'rest_framework_microservice',
]

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

For log off / token black listing feature to work, you also need to include the following in django settings:

INSTALLED_APPS = [
    ...,
    'rest_framework_simplejwt.token_blacklist'
]

and then run django migrations.

REST API endpoints

{{domain}}/auth/sign-in/

Sign in directly against Django backend using username and password, retrieves access token and response body and refresh token as HttpOnly cookie. The response body also contains a CSRF_token, which matches the same token set in the HttpOnly cookie.

curl --location --request POST '127.0.0.1:8000/auth/sign-in/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "admin",
    "password": "admin"
}'

{{domain}}/auth/social-exchange/

Submits JWT tokens from an IDP (AWS Cognito), and in exchange for JWT tokens issue by Django server. This will create a Django user if it does not already exist in the database. The response is the same as sign-in endpoint above.

curl --location --request POST '127.0.0.1:8000/auth/social-exchange/' \
--header 'Authorization: Bearer jwt_token_string \
--header 'Content-Type: application/json' \
--data-raw '{
    "id_token": "id_token_from_idp",
    "access_token": "access_token_from_idp",
    "refresh_token": "refresh_token_from_idp",
    "expires_in": 300,
    "token_type": "Bearer"
}'

{{domain}}/auth/refresh/

This endpoint accepts the refresh token and csrf token in HttpOnly cookies, and return an access token in response body.

curl --location --request POST '127.0.0.1:8000/auth/refresh/' \
--header 'Authorization: Bearer jwt_token_string \
--header 'Content-Type: application/json' \
--data-raw '{
    "CSRF_token": "csrf_token"
}'

{{domain}}/auth/logoff/

This endpoint requires rest_framework_simplejwt.token_blacklist to have been installed. Call this endpoint to blacklist the current refresh token.

curl --location --request POST '127.0.0.1:8000/auth/logoff/' \
--header 'Authorization: Bearer jwt_token_string \
--header 'Content-Type: application/json' \
--data-raw '{
    "CSRF_token": "csrf_token"
}'

Settings

Settings are specified in Django settings.py under REST_FRAMEWORK_MICROSERVICE, the defaults are the following:

REST_FRAMEWORK_MICROSERVICE = {
    "REFRESH_COOKIE_NAME": "refresh_cookie",
    "REFRESH_COOKIE_PATH": "/auth",
    "IDP": {
        "PROVIDER": "aws",
        "REGION": "us-west-2",
        "USER_POOL": "us-west-2_abcdefg",
        "CLIENT_ID": "abcdefg",
    },
    "CUSTOM_TOKEN_USER_ATTRIBUTES": [],
    "CUSTOM_TOKEN_CALLABLE_ATTRIBUTES": [],
    "COOKIE_SALT": "extra",
    "USER_SERIALIZER_CLASS": None,
    "USER_MODEL_UUID_FIELD": None,
}

Name of refresh cookie to set in HTTP header.

URL path of refresh cookie, this should be a string that starts with a slash, ie: "/auth". This path needs to match the path of authentication endpoint path set in urls.py.

IDP

A dictionary containing IDP attributes:

  • PROVIDER: a string identifying what IDP backend to use, defaults to 'aws' (Currently only AWS Cognito is supported.)
  • REGION: user pool region.
  • USER_POOL: user pool identifier used with the IDP.
  • CLIENT_ID: IDP client id for your application.

CUSTOM_TOKEN_USER_ATTRIBUTES

The list of Django user attributes to be copied to token as claims. i.e.: ['is_active',].

CUSTOM_TOKEN_CALLABLE_ATTRIBUTES

This is used to customize claims which cannot be done by simply using CUSTOM_TOKEN_USER_ATTRIBUTES setting. This should be a list of dictionaries containing attr_name and attr_getter. i.e. : [{'attr_name': 'preferences', 'attr_getter': 'my_module.some_file.get_user_preferences'}, ...]

The function specified in attr_getter should accept an argument of a Django user instance.

Salt to be used when signing cookie.

USER_SERIALIZER_CLASS

Defaults to None. If specified, the default view serializers will try to add a user object representing the user. The content of the user object is defined by USER_SERIALIZER_CLASS.

USER_MODEL_UUID_FIELD

Defaults to None. Used to specify a field on the Django user model that can be used to store UUID from IDP.

Customizing token claims

You can include additional user attributes in the token claims by specifying them in the CUSTOM_TOKEN_USER_ATTRIBUTES.

You can also specify functions to return the value for custom claims by using CUSTOM_TOKEN_CALLABLE_ATTRIBUTES.

# settings.py
REST_FRAMEWORK_MICROSERVICE = {
  ...,
  'CUSTOM_TOKEN_CALLABLE_ATTRIBUTES': [
        {'attr_name': 'user_services',
         'attr_getter': 'my_module.token_claims.get_user_subscribed_services'
         }
    ]
}

# my_module.token_claims.py
def get_user_subscribed_services(user):
  return user.subscribed_services

If you are using djangorestframework-simplejwt version <= 5.0.0, you will also need to extend the rest_framework_simplejwt.models.TokenUser to include the additional claims. This is only applicable when using older versions.

from functools import cached_property
from rest_framework_simplejwt.models import TokenUser

class CustomTokenUser(TokenUser):
    """
    Extend TokenUser and adds custom attributes to be pulled from TokenUser.
    This class should be specified in Django settings SIMPLE_JWT.TOKEN_USER_CLASS
    """

    @cached_property
    def first_name(self):
        return self.token.get('first_name', None)

and include the following Django setting:

SIMPLE_JWT = {
    'TOKEN_USER_CLASS': 'microservice.models.CustomTokenUser'
}

Third-party IDP

This package currently supports Cognito as an identity provider. You can use AWS Cognito Userpool to enable social authentication. Screenshot below for an example of setting up Cognito with Google sign in.

AWS Cognito Userpool configurations

Google OAuth configurations

Metadata

Release files for django-rest-microservice 1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for django-rest-microservice 1.3
File Size Uploaded Provenance Actions
django_rest_microservice-1.3.tar.gz 10.3 kB Without provenance Details for django_rest_microservice-1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for django-rest-microservice 1.3
File Interpreter ABI Platform Actions
django_rest_microservice-1.3-py3-none-any.whl Python 3 none any Details for django_rest_microservice-1.3-py3-none-any.whl

Total release size: 23.4 kB

Release files / django_rest_microservice-1.3.tar.gz

Download URL django_rest_microservice-1.3.tar.gz
Size 10.3 kB
Tags Source
SHA-256 checksum
How to use checksums
13f59718d87f33b00828530bfe5d73e6e8f1d325352ae92cbde0e75110d52360
BLAKE2b-256 checksum
How to use checksums
cc100b5180fa4c4124b693d44abe99c900aaf8f8e616ce60e80becb3f6c4afec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.9

Release files / django_rest_microservice-1.3-py3-none-any.whl

Download URL django_rest_microservice-1.3-py3-none-any.whl
Size 13.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8e3a814941d332ef6eb40ae7ab071583bf6c11819ac012c8bbfaa53b917a00b9
BLAKE2b-256 checksum
How to use checksums
082a1929530a85b1e74bb41d55f0de18f8be1f262ce896e1bd64baf0488d4dea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.9

Security for django-rest-microservice 1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page