django-pfx 1.4.dev28__tar.gz → 1.4.dev30__tar.gz

{django-pfx-1.4.dev28 → django-pfx-1.4.dev30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.4.dev28
+Version: 1.4.dev30
 Summary: Django PFX is a toolkit designed to streamline the development of RESTful APIs using the Django framework.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com

{django-pfx-1.4.dev28 → django-pfx-1.4.dev30}/django_pfx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.4.dev28
+Version: 1.4.dev30
 Summary: Django PFX is a toolkit designed to streamline the development of RESTful APIs using the Django framework.
 Author: Hervé Martinet
 Author-email: herve.martinet@gmail.com

{django-pfx-1.4.dev28 → django-pfx-1.4.dev30}/django_pfx.egg-info/SOURCES.txt

@@ -67,6 +67,7 @@ pfx/pfxcore/models/login_ban.py
 pfx/pfxcore/models/not_null_fields.py
 pfx/pfxcore/models/otp_user_mixin.py
 pfx/pfxcore/models/pfx_models.py
+pfx/pfxcore/models/pfx_user.py
 pfx/pfxcore/models/user_filtered_queryset_mixin.py
 pfx/pfxcore/serializers/__init__.py
 pfx/pfxcore/serializers/json.py

{django-pfx-1.4.dev28 → django-pfx-1.4.dev30}/doc/source/api.views.rst

@@ -32,6 +32,18 @@ API Reference
     :undoc-members:
     :show-inheritance:
 
+.. autoclass:: pfx.pfxcore.models.AbstractPFXBaseUser
+    :members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.models.OtpUserMixin
+    :members:
+    :show-inheritance:
+
+.. autoclass:: pfx.pfxcore.models.PFXUser
+    :members:
+    :show-inheritance:
+
 ``pfx.pfxcore.views``
 *********************
 
@@ -43,12 +55,17 @@ Base services
     :undoc-members:
     :show-inheritance:
 
+.. autoclass:: pfx.pfxcore.views.SignupView
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 .. autoclass:: pfx.pfxcore.views.ForgottenPasswordView
     :members:
     :undoc-members:
     :show-inheritance:
 
-.. autoclass:: pfx.pfxcore.views.SignupView
+.. autoclass:: pfx.pfxcore.views.OtpEmailView
     :members:
     :undoc-members:
     :show-inheritance:

{django-pfx-1.4.dev28 → django-pfx-1.4.dev30}/doc/source/authentication.md

@@ -1,20 +1,21 @@
 # Authentication
 
 Django PFX offers services and middlewares for managing user authentication in your API.
-These services replicate some of the functionalities provided by the `django.contrib.auth`
+These services replicate some of the functionalities provided by the {mod}`django.contrib.auth`
 package but in the form of RESTful services.
 They utilize the same user model and authentication backend features,
 including password validation and hashing.
 
 ## User Model
 
-You have the option to use the standard `django.contrib.auth.models.User`,
+You have the option to use the standard Django User with {class}`pfx.pfxcore.models.PFXUser`
+(which is a {class}`django.contrib.auth.models.User` with PFX required mixins),
 but you may prefer to use your own model. To do this, create your own user class.
 
 ```python
-from django.contrib.auth.models import AbstractUser
+from pfx.pfxcore.models import AbstractPFXBaseUser
 
-class MyUser(AbstractUser):
+class MyUser(AbstractPFXBaseUser):
     pass
 ```
 
@@ -28,8 +29,8 @@ AUTH_USER_MODEL = "myapp.MyUser"
 
 There are two authentication modes available: cookie and bearer token. You can activate either or both by enabling the following middlewares:
 
-* `'pfx.pfxcore.middleware.AuthenticationMiddleware'` (bearer token)
-* `'pfx.pfxcore.middleware.CookieAuthenticationMiddleware'` (cookie)
+* {class}`pfx.pfxcore.middleware.AuthenticationMiddleware` (bearer token)
+* {class}`pfx.pfxcore.middleware.CookieAuthenticationMiddleware` (cookie)
 
 ### Token Validity
 
@@ -40,7 +41,7 @@ You can customize token validity by configuring these parameters:
 
 ### Cookie Settings
 
-To use the `CookieAuthenticationMiddleware`, you need to configure the following settings:
+To use the {class}`pfx.pfxcore.middleware.CookieAuthenticationMiddleware`, you need to configure the following settings:
 
 * `PFX_COOKIE_DOMAIN`: The cookie domain
 * `PFX_COOKIE_SECURE`: `Secure` attribute of the cookie (`True`/`False`)
@@ -48,28 +49,55 @@ To use the `CookieAuthenticationMiddleware`, you need to configure the following
 
 See the [MDN Website](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies) for more details.
 
+### Temporary bans
+
+Users will be temporarily banned after several unsuccessful login attempts.
+
+In the event of a temporary ban, login services will respond with the HTTP code `429` and
+the `Retry-After` header.
+
+#### Settings
+
+* `PFX_LOGIN_BAN_FAILED_NUMBER`: The number of failed login attempts before banning. To deactivate the ban completely, set `0` (optional, default `5`).
+* `PFX_LOGIN_BAN_SECONDS_START`: The number of seconds for the first ban (optional, default `60`).
+* `PFX_LOGIN_BAN_SECONDS_STEP`: The number of seconds to be added to the previous ban for consecutive bans (optional, default `60`).
+
 ### Multifactor Authentication
 Multifactor authentication can be enabled in django-pfx Authentication API.
 
 PFX currently provides MFA with One Time Password (OTP), compatible with FreeOTP,
 Google Authenticator and other OTP app.
 
-To enable this feature, install django-pfx with otp
+To enable this feature, install django-pfx with otp.
 
 ```bash
 pip install django-pfx[otp]
 ```
 
-Then the user class must use the ```OtpUserMixin```
+Then the user class must use the {class}`pfx.pfxcore.models.OtpUserMixin`.
 
 ```python
-from django.contrib.auth.models import AbstractUser
-from pfx.pfxcore.models import OtpUserMixin
+from pfx.pfxcore.models import PFXUser, OtpUserMixin
 
-class MyUser(OtpUserMixin, AbstractUser):
+class MyUser(OtpUserMixin, PFXUser):
     pass
 ```
 
+or
+
+```python
+from pfx.pfxcore.models import AbstractPFXBaseUser, OtpUserMixin
+
+class MyUser(OtpUserMixin, AbstractPFXBaseUser):
+    pass
+```
+
+#### Settings
+
+* `PFX_TOKEN_OTP_VALIDITY`: Validity for OTP tokens (corresponds to the maximum time to enter
+  an OTP code after logging in with a password) (optional, default `{'minutes': 15}`)
+* `PFX_HOTP_CODE_VALIDITY`: Validity of HOTP codes in minutes (used to send code by email) (optional, default `15`).
+
 The user can then enable or disable the OTP auth using the [services documented below](#enable-mfa-otp).
 
 ## Services
@@ -263,7 +291,7 @@ like so: `https://example.com/reset-password?token={token}&uidb64={uidb64}`.
 Your reset page should then call the "set password" service with these two parameters.
 
 You can override this class if you need to customize the email templates.
-Refer to the [API doc](api.views.rst#pfx.pfxcore.views.ForgottenPasswordView) for more details.
+Refer to {class}`pfx.pfxcore.views.ForgottenPasswordView` for more details.
 
 **Request :** `POST` `/auth/forgotten-password`
 
@@ -288,7 +316,7 @@ like so: `https://example.com/reset-password?token={token}&uidb64={uidb64}`.
 Your reset page should then call the "set password" service with these two parameters.
 
 You can override this class if you need to customize the user or email templates.
-Refer to the [API doc](api.views.rst#pfx.pfxcore.views.SignupView) for more details.
+Refer to {class}`pfx.pfxcore.views.SignupView` for more details.
 
 **Request :** `POST` `/auth/signup`
 

{django-pfx-1.4.dev28 → django-pfx-1.4.dev30}/pfx/pfxcore/models/__init__.py

@@ -13,4 +13,5 @@ from .pfx_models import (
     PFXModelMixin,
     UniqueConstraint,
 )
+from .pfx_user import PFXUser
 from .user_filtered_queryset_mixin import UserFilteredQuerySetMixin

{django-pfx-1.4.dev28 → django-pfx-1.4.dev30}/pfx/pfxcore/models/abstract_pfx_base_user.py

@@ -2,6 +2,8 @@ from django.contrib.auth.models import AbstractBaseUser
 
 
 class AbstractPFXBaseUser(AbstractBaseUser):
+    """The base abstract user for PFX."""
+
     class Meta:
         abstract = True
 
@@ -10,6 +12,7 @@ class AbstractPFXBaseUser(AbstractBaseUser):
         Return a user secret to sign JWT token.
 
         If not empty, the JWT token validity depends on all values
-        user to build the return string.
+        user to build the return string. So, each time the returned value
+        changes, the previously issued tokens will no longer be valid.
         """
         return self.password

{django-pfx-1.4.dev28 → django-pfx-1.4.dev30}/pfx/pfxcore/models/otp_user_mixin.py

@@ -8,23 +8,42 @@ from pfx.pfxcore.settings import settings
 
 
 class OtpUserMixin(models.Model):
+    """A mixin to enable OTP MFA on a user class."""
+
+    #: OTP secret token.
     otp_secret_token = models.CharField(
         _("OTP secret token"), max_length=32, null=True,
         blank=True, unique=True)
+    #: Temporary OTP secret token (needs confirmation).
     otp_secret_token_tmp = models.CharField(
         _("Temporary OTP secret token"), max_length=32, null=True, blank=True)
+    #: HOTP count.
     hotp_count = models.IntegerField(_("HOTP count"), default=0)
+    #: HOTP expiry.
     hotp_expiry = models.DateTimeField(_("HOTP expiry"), default=timezone.now)
 
     class Meta:
         abstract = True
 
     def enable_otp(self):
+        """Activate OTP for this user.
+
+        Generates a new temporary OTP secret token. To complete activation,
+        call `confirm_otp` with a valid code.
+        """
         import pyotp
         self.otp_secret_token_tmp = pyotp.random_base32()
         self.save(update_fields=['otp_secret_token_tmp'])
 
     def confirm_otp(self, otp_code):
+        """Confirm OTP activation for this user.
+
+        Set the OTP secret token from the temporary one if the provided
+        code is valid.
+
+        :param otp_code: A valid OTP code for the temporary OTP secret key.
+        :returns: `True` if success, `False` otherwise.
+        """
         if self.is_otp_valid(otp_code, tmp=True):
             self.otp_secret_token = self.otp_secret_token_tmp
             self.otp_secret_token_tmp = None
@@ -34,10 +53,16 @@ class OtpUserMixin(models.Model):
         return False
 
     def disable_otp(self):
+        """Disable OTP for this user.
+
+        Remove the OTP secret token.
+        """
         self.otp_secret_token = None
         self.save(update_fields=['otp_secret_token'])
 
     def get_otp_setup_uri(self, tmp=False):
+        """Return the setup URL for OTP activation.
+        """
         import pyotp
         return pyotp.totp.TOTP(
             tmp and self.otp_secret_token_tmp or
@@ -45,6 +70,13 @@ class OtpUserMixin(models.Model):
                 name=self.email, issuer_name=settings.PFX_SITE_NAME)
 
     def is_otp_valid(self, otp_code, tmp=False):
+        """Verify an OTP code.
+
+        :param otp_code: A valid OTP code for the OTP secret key.
+        :param tmp: If `True`, verify the code with the temporary
+            OTP secret key.
+        :returns: `True` if the code is valid, `False` otherwise.
+        """
         import pyotp
         totp = pyotp.parse_uri(self.get_otp_setup_uri(tmp=tmp))
         valid = totp.verify(otp_code)
@@ -56,10 +88,17 @@ class OtpUserMixin(models.Model):
         return valid
 
     def get_user_jwt_signature_key(self):
+        """Return a user secret to sign JWT token.
+
+        If the user inherit :class:`pfx.pfxcore.models.AbstractPFXBaseUser`,
+        add the OTP secret token to the user signature."""
         return super().get_user_jwt_signature_key() + (
             self.otp_secret_token or "")
 
     def get_hotp_code(self):
+        """Return a new valid HOTP code.
+
+        Increment the HOTP counter and reset the expiry."""
         import pyotp
         if not self.otp_secret_token:
             raise Exception("OTP disabled")

django-pfx-1.4.dev30/pfx/pfxcore/models/pfx_user.py

@@ -0,0 +1,11 @@
+from django.contrib.auth.models import AbstractUser
+
+from .abstract_pfx_base_user import AbstractPFXBaseUser
+
+
+class PFXUser(AbstractUser, AbstractPFXBaseUser):
+    """The Django User with PFX mixin.
+    """
+
+    class Meta(AbstractUser.Meta):
+        swappable = "AUTH_USER_MODEL"

{django-pfx-1.4.dev28 → django-pfx-1.4.dev30}/pfx/pfxcore/views/authentication_views.py

@@ -783,7 +783,7 @@ class ForgottenPasswordView(SendMessageTokenMixin, BodyMixin, BaseRestView):
 
 @rest_view("/auth/otp")
 class OtpEmailView(BodyMixin, JWTTokenDecodeMixin, BaseRestView):
-    """View for forgotten password service."""
+    """View for the OTP code email service."""
     #: The email template.
     email_template_name = 'registration/otp_code_email.txt'
     #: The email subject template.
@@ -852,7 +852,7 @@ class OtpEmailView(BodyMixin, JWTTokenDecodeMixin, BaseRestView):
             'message': _('A new authentication code has been sent by email.')})
 
     def send_otp_message(self, user):
-        """Send an email to a user with an OTP code.
+        """Send an email to a user with an OTP code to a user.
 
         :param user: The user
         """

{django-pfx-1.4.dev28 → django-pfx-1.4.dev30}/tests/tests/test_auth_api.py

@@ -1247,7 +1247,7 @@ class AuthAPITest(TestAssertMixin, TransactionTestCase):
             code_match = re.search(
                 r'Authentication code: (\d{6})', mail.outbox[0].body)
             self.assertIsNotNone(code_match)
-            otp_code = int(code_match.group(1))
+            otp_code = code_match.group(1)
 
             response = self.client.post('/api/auth/otp/login', dict(
                 token=otp_token,