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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.4.dev26
+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.dev26 → 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.dev26
+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.dev26 → 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
@@ -127,6 +128,7 @@ tests/tests/test_locale_api.py
 tests/tests/test_perm_tests.py
 tests/tests/test_perms_api.py
 tests/tests/test_profiling_middleware.py
+tests/tests/test_settings.py
 tests/tests/test_shortcuts.py
 tests/tests/test_timezone_middleware.py
 tests/tests/test_tools.py

{django-pfx-1.4.dev26 → 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.dev26 → 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.dev26 → django-pfx-1.4.dev30}/pfx/pfxcore/decorator/rest.py

@@ -7,11 +7,9 @@ from apispec.utils import deepupdate
 
 from pfx.pfxcore.exceptions import APIError
 from pfx.pfxcore.http import JsonResponse
-from pfx.pfxcore.settings import PFXSettings
+from pfx.pfxcore.settings import settings
 from pfx.pfxcore.test import format_request
 
-settings = PFXSettings()
-
 logger = logging.getLogger(__name__)
 
 

{django-pfx-1.4.dev26 → django-pfx-1.4.dev30}/pfx/pfxcore/management/commands/makeapidoc.py

@@ -11,10 +11,9 @@ from apispec.yaml_utils import load_operations_from_docstring
 
 from pfx.pfxcore import __PFX_VIEWS__
 from pfx.pfxcore.apidoc import __PARAMETERS__, __TAGS__, ParameterGroup
-from pfx.pfxcore.settings import PFXSettings
+from pfx.pfxcore.settings import settings
 from pfx.pfxcore.views import FilterGroup, ModelMixin
 
-settings = PFXSettings()
 DEFAULT_TEMPLATE = dict(
     title="PFX API",
     version="1.0.0",

{django-pfx-1.4.dev26 → django-pfx-1.4.dev30}/pfx/pfxcore/middleware/profiling.py

@@ -11,10 +11,9 @@ from django.utils.deprecation import MiddlewareMixin
 
 import sqlparse
 
-from pfx.pfxcore.settings import PFXSettings
+from pfx.pfxcore.settings import settings
 
 logger = logging.getLogger(__name__)
-settings = PFXSettings()
 rid = ContextVar('var')
 
 

{django-pfx-1.4.dev26 → 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.dev26 → 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.dev26 → django-pfx-1.4.dev30}/pfx/pfxcore/models/login_ban.py

@@ -4,9 +4,7 @@ from django.db import models
 from django.utils import timezone
 from django.utils.translation import gettext_lazy as _
 
-from pfx.pfxcore.settings import PFXSettings
-
-settings = PFXSettings()
+from pfx.pfxcore.settings import settings
 
 
 class LoginBanQuerySet(models.QuerySet):

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

@@ -4,29 +4,46 @@ from django.db import models
 from django.utils import timezone
 from django.utils.translation import gettext_lazy as _
 
-from pfx.pfxcore.settings import PFXSettings
-
-settings = PFXSettings()
+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
@@ -36,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
@@ -47,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)
@@ -58,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.dev30/pfx/pfxcore/settings.py

@@ -0,0 +1,22 @@
+from django.conf import settings as django_settings
+from django.core.exceptions import ImproperlyConfigured
+
+from . import default_settings
+
+
+class PFXSettings:
+    def __getattr__(self, name):
+        try:
+            val = getattr(django_settings, name)
+        except AttributeError:
+            if hasattr(default_settings, name):
+                val = getattr(default_settings, name)
+            else:
+                raise
+        if name == "PFX_SECRET_KEY" and not val:
+            raise ImproperlyConfigured(
+                "The PFX_SECRET_KEY setting must not be empty.")
+        return val
+
+
+settings = PFXSettings()

{django-pfx-1.4.dev26 → django-pfx-1.4.dev30}/pfx/pfxcore/shortcuts.py

@@ -5,9 +5,7 @@ from datetime import date
 from django.core.exceptions import ObjectDoesNotExist
 from django.utils.translation import gettext_lazy as _
 
-from pfx.pfxcore.settings import PFXSettings
-
-settings = PFXSettings()
+from .settings import settings
 
 logger = logging.getLogger(__name__)
 

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

@@ -32,7 +32,7 @@ from pfx.pfxcore.http import JsonResponse
 from pfx.pfxcore.middleware.authentication import JWTTokenDecodeMixin
 from pfx.pfxcore.models import CacheableMixin, OtpUserMixin
 from pfx.pfxcore.models.login_ban import LoginBan
-from pfx.pfxcore.settings import PFXSettings
+from pfx.pfxcore.settings import settings
 from pfx.pfxcore.shortcuts import delete_token_cookie
 
 from .rest_views import (
@@ -42,7 +42,6 @@ from .rest_views import (
     ModelMixin,
 )
 
-settings = PFXSettings()
 logger = logging.getLogger(__name__)
 UserModel = get_user_model()
 AUTHENTICATION_TAG = Tag("Authentication")
@@ -784,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.
@@ -853,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.dev26 → django-pfx-1.4.dev30}/tests/tests/__init__.py

@@ -11,6 +11,7 @@ from .test_locale_api import LocaleAPITest
 from .test_perm_tests import PermTestsTest
 from .test_perms_api import PermsAPITest
 from .test_profiling_middleware import ProfilingMiddlewareTest
+from .test_settings import TestSettings
 from .test_shortcuts import ShortcutTest
 from .test_timezone_middleware import TimezoneMiddlewareTest
 from .test_tools import TestTools

{django-pfx-1.4.dev26 → 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,

django-pfx-1.4.dev30/tests/tests/test_settings.py

@@ -0,0 +1,23 @@
+from datetime import timedelta
+
+from django.core.exceptions import ImproperlyConfigured
+from django.test import TestCase, override_settings
+
+from pfx.pfxcore.test import TestAssertMixin
+from pfx.pfxcore.views import AuthenticationView
+from tests.models import User
+
+
+class TestSettings(TestAssertMixin, TestCase):
+
+    @override_settings(PFX_SECRET_KEY="")
+    def test_mandatory_pfx_secret_key(self):
+        user = User.objects.create_user(
+            username='user',
+            email="user@example.com",
+            password='test',
+            first_name='User',
+            last_name='Test')
+
+        with self.assertRaises(ImproperlyConfigured):
+            AuthenticationView()._prepare_token(user, timedelta())

django-pfx-1.4.dev26/pfx/pfxcore/settings.py

@@ -1,11 +0,0 @@
-from django.conf import settings
-
-from . import default_settings
-
-
-class PFXSettings:
-    def __getattr__(self, attr):
-        try:
-            return getattr(settings, attr)
-        except AttributeError:
-            return getattr(default_settings, attr)