Improve single use with settings and more docs

Author: SebastianKapunkt

docs/settings.rst

@@ -17,6 +17,14 @@ Mail Auth settings
     Defines the URL the user will be redirected to, after requesting an
     authentication message.
 
+.. attribute:: LOGIN_TOKEN_SINGLE_USE
+
+    Default: ``True``
+
+    Defines if a token can be used more than once.
+    If ``True``, the same token can only be used once and will be invalid the next try.
+    If ``False``, the same token can be used multiple times and remains valid until expired.
+
 Django related settings
 -----------------------
 

mailauth/backends.py

@@ -12,9 +12,10 @@ class MailAuthBackend(ModelBackend):
 
     def authenticate(self, request, token=None):
         max_age = getattr(settings, 'LOGIN_URL_TIMEOUT', 60 * 15)
+        single_use = getattr(settings, 'LOGIN_TOKEN_SINGLE_USE', True)
 
         try:
-            user = self.signer.unsign(token, max_age=max_age)
+            user = self.signer.unsign(token, max_age=max_age, single_use=single_use)
         except (get_user_model().DoesNotExist, BadSignature):
             return
         else:

mailauth/signing.py

@@ -1,6 +1,5 @@
 from django.contrib.auth import get_user_model
 from django.core import signing
-from django.core.signing import SignatureExpired
 from django.utils import baseconv
 
 __all__ = (
@@ -53,15 +52,19 @@ def _make_hash_value(self, user):
         user_pk = baseconv.base62.encode(user.pk)
         return self.sep.join((user_pk, last_login))
 
-    def unsign(self, value, max_age=None, allow_multi_use=False):
+    def unsign(self, value, max_age=None, single_use=True):
         """
         Verify access token and return user, if the token is valid.
 
         Args:
             value (str): URL safe base64 encoded access token.
             max_age (datetime.timedelta): Maximum age an access token to be valid.
-            allow_multi_use: If True allows the token to be used more than once
-
+            single_use (bool):
+                If ``True``, the same token can only be used once and will be invalid
+                the next try.
+                If ``False``, the same token can be used multiple times and remains
+                valid until expired.
+                Default: ``True``
         Returns:
             django.contrib.user.models.BaseUser: Return user object for given
             access token.
@@ -86,11 +89,9 @@ def unsign(self, value, max_age=None, allow_multi_use=False):
         except get_user_model().DoesNotExist as e:
             raise UserDoesNotExist("User with pk=%s does not exist" % user_pk) from e
         else:
-            if last_login != '' and self.to_timestamp(user.last_login) != last_login:
-                if allow_multi_use:
-                    return user
-                else:
-                    raise SignatureExpired(
-                        "The access token for %r seems used" % user
-                    )
+            if (single_use and last_login != '' and
+                    self.to_timestamp(user.last_login) != last_login):
+                raise signing.SignatureExpired(
+                    "The access token for %r seems used" % user
+                )
             return user

tests/test_signing.py

@@ -39,20 +39,21 @@ def test_unsign__last_login(self, db, signer, signature):
         ):
             signer.unsign(signature)
 
-    def test_unsing__allow_multiple_use(self, db, signer, signature):
+    def test_unsing__single_use(self, db, signer, signature):
         user = get_user_model().objects.create_user(
             pk=1337,
             email='spiderman@avengers.com',
             # later date, that does not match the signature (token was used)
             last_login=timezone.datetime(2012, 7, 3, tzinfo=timezone.utc),
         )
-        assert user == signer.unsign(signature, allow_multi_use=True)
-        assert user == signer.unsign(signature, allow_multi_use=True)
+        assert user == signer.unsign(signature, single_use=False)
+        # test a second time to make sure token can be used more than one time
+        assert user == signer.unsign(signature, single_use=False)
         with pytest.raises(
             SignatureExpired,
             match="The access token for <EmailUser: spiderman@avengers.com> seems used"
         ):
-            signer.unsign(signature, allow_multi_use=False)
+            signer.unsign(signature, single_use=True)
 
     def test_to_timestamp(self):
         value = timezone.datetime(2002, 5, 3, tzinfo=timezone.utc)