Session Tokens#
Introduction#
When using allauth headless in non-browser contexts, such as mobile apps, a
session token is used to keep track of the authentication state. This session
token is handed over by the app by providing the X-Session-Token request
header. The token is only accepted while the Django session still authenticates
the user using Django’s standard session auth hash check. Logging out or changing
the password therefore invalidates it immediately.
If you do not have any requirements that prescribe a specific token strategy,
the simplest way forward is to use the X-Session-Token authentication
mechanism for your own APIs as well. In order to do so, integration with Django
Ninja and Django REST framework is offered out of the box.
Securing Your API Endpoints#
Django Ninja#
For Django Ninja, the following security class is available:
An example on how to use that security class in your own code is listed below:
from allauth.headless.contrib.ninja.security import x_session_token_auth
from ninja import NinjaAPI
api = NinjaAPI()
@api.get("/your/own/api", auth=[x_session_token_auth])
def your_own_api(request):
...
By default, missing or invalid session tokens and sessions that do not authenticate a user are rejected. To make authentication optional, subclass the security class and enable anonymous users:
from allauth.headless.contrib.ninja.security import XSessionTokenAuth
class OptionalXSessionTokenAuth(XSessionTokenAuth):
allow_anonymous_users = True
Missing tokens and valid sessions without an authenticated user then produce
an AnonymousUser. Invalid session tokens remain rejected. To allow those as
well, set allow_invalid_session_tokens = True. In both cases,
request.user is set to the returned AnonymousUser.
Django REST framework#
For Django REST framework, the following authentication class is available:
An example on how to use that authentication class in your own code is listed below:
from allauth.headless.contrib.rest_framework.authentication import (
XSessionTokenAuthentication,
)
from rest_framework import permissions
from rest_framework.views import APIView
class YourOwnAPIView(APIView):
authentication_classes = [
XSessionTokenAuthentication,
]
permission_classes = [permissions.IsAuthenticated]
def get(self, request):
...
By default, invalid session tokens and sessions that do not authenticate an
active user are ignored. This matches Django REST framework’s session
authentication behavior. To reject either case, subclass the authentication
class and set the corresponding option to False:
class StrictXSessionTokenAuthentication(XSessionTokenAuthentication):
allow_anonymous_users = False
allow_invalid_session_tokens = False
When disabled, the corresponding condition raises DRF’s
AuthenticationFailed exception. If this authentication class is listed
first on the view, DRF responds with status 401 and an
X-Session-Token authentication challenge.