diff --git a/docs/index.rst b/docs/index.rst index 1aefc1a7e..fbf54629e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,7 +51,7 @@ Contents creating_tokens_manually token_types blacklist_app - experimental_features + stateless_user_authentication development_and_contributing drf_yasg_integration rest_framework_simplejwt diff --git a/docs/settings.rst b/docs/settings.rst index 1e065b0ab..3f89c21c9 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -239,7 +239,7 @@ store such a value. -------------------- A stateless user object which is backed by a validated token. Used only for -the experimental JWTTokenUserAuthentication authentication backend. The value +the JWTStatelessUserAuthentication authentication backend. The value is a dotted path to your subclass of ``rest_framework_simplejwt.models.TokenUser``, which also is the default. diff --git a/docs/experimental_features.rst b/docs/stateless_user_authentication.rst similarity index 67% rename from docs/experimental_features.rst rename to docs/stateless_user_authentication.rst index 13adca706..a0dfb7705 100644 --- a/docs/experimental_features.rst +++ b/docs/stateless_user_authentication.rst @@ -1,19 +1,19 @@ -.. _experimental_features: +.. _stateless_user_authentication: -Experimental features +Stateless User Authentication ===================== -JWTTokenUserAuthentication backend +JWTStatelessUserAuthentication backend ---------------------------------- -The ``JWTTokenUserAuthentication`` backend's ``authenticate`` method does not +The ``JWTStatelessUserAuthentication`` backend's ``authenticate`` method does not perform a database lookup to obtain a user instance. Instead, it returns a ``rest_framework_simplejwt.models.TokenUser`` instance which acts as a stateless user object backed only by a validated token instead of a record in a database. This can facilitate developing single sign-on functionality between separately hosted Django apps which all share the same token secret key. To use this feature, add the -``rest_framework_simplejwt.authentication.JWTTokenUserAuthentication`` backend +``rest_framework_simplejwt.authentication.JWTStatelessUserAuthentication`` backend (instead of the default ``JWTAuthentication`` backend) to the Django REST Framework's ``DEFAULT_AUTHENTICATION_CLASSES`` config setting: @@ -23,7 +23,7 @@ Framework's ``DEFAULT_AUTHENTICATION_CLASSES`` config setting: ... 'DEFAULT_AUTHENTICATION_CLASSES': ( ... - 'rest_framework_simplejwt.authentication.JWTTokenUserAuthentication', + 'rest_framework_simplejwt.authentication.JWTStatelessUserAuthentication', ) ... } diff --git a/rest_framework_simplejwt/authentication.py b/rest_framework_simplejwt/authentication.py index f7ad03537..15767cddd 100644 --- a/rest_framework_simplejwt/authentication.py +++ b/rest_framework_simplejwt/authentication.py @@ -126,7 +126,12 @@ def get_user(self, validated_token): return user -class JWTTokenUserAuthentication(JWTAuthentication): +class JWTStatelessUserAuthentication(JWTAuthentication): + """ + An authentication plugin that authenticates requests through a JSON web + token provided in a request header without performing a database lookup to obtain a user instance. + """ + def get_user(self, validated_token): """ Returns a stateless user object which is backed by the given validated @@ -140,6 +145,9 @@ def get_user(self, validated_token): return api_settings.TOKEN_USER_CLASS(validated_token) +JWTTokenUserAuthentication = JWTStatelessUserAuthentication + + def default_user_authentication_rule(user): # Prior to Django 1.10, inactive users could be authenticated with the # default `ModelBackend`. As of Django 1.10, the `ModelBackend` diff --git a/rest_framework_simplejwt/models.py b/rest_framework_simplejwt/models.py index 959b7f597..234de73e3 100644 --- a/rest_framework_simplejwt/models.py +++ b/rest_framework_simplejwt/models.py @@ -9,9 +9,9 @@ class TokenUser: """ A dummy user class modeled after django.contrib.auth.models.AnonymousUser. - Used in conjunction with the `JWTTokenUserAuthentication` backend to + Used in conjunction with the `JWTStatelessUserAuthentication` backend to implement single sign-on functionality across services which share the same - secret key. `JWTTokenUserAuthentication` will return an instance of this + secret key. `JWTStatelessUserAuthentication` will return an instance of this class instead of a `User` model instance. Instances of this class act as stateless user objects which are backed by validated tokens. """ diff --git a/tests/test_authentication.py b/tests/test_authentication.py index a8f4ff4b8..917f3993d 100644 --- a/tests/test_authentication.py +++ b/tests/test_authentication.py @@ -157,9 +157,9 @@ def test_get_user(self): self.assertEqual(self.backend.get_user(payload).id, u.id) -class TestJWTTokenUserAuthentication(TestCase): +class TestJWTStatelessUserAuthentication(TestCase): def setUp(self): - self.backend = authentication.JWTTokenUserAuthentication() + self.backend = authentication.JWTStatelessUserAuthentication() def test_get_user(self): payload = {"some_other_id": "foo"}