django-pfx 1.4.dev16__tar.gz → 1.4.dev22__tar.gz

{django-pfx-1.4.dev16 → django-pfx-1.4.dev22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.4.dev16
+Version: 1.4.dev22
 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.dev16 → django-pfx-1.4.dev22}/django_pfx.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.4.dev16
+Version: 1.4.dev22
 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.dev16 → django-pfx-1.4.dev22}/django_pfx.egg-info/SOURCES.txt

@@ -61,7 +61,9 @@ pfx/pfxcore/middleware/authentication.py
 pfx/pfxcore/middleware/locale.py
 pfx/pfxcore/middleware/profiling.py
 pfx/pfxcore/models/__init__.py
+pfx/pfxcore/models/abstract_pfx_base_user.py
 pfx/pfxcore/models/cache_mixins.py
+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

{django-pfx-1.4.dev16 → django-pfx-1.4.dev22}/doc/conf.py

@@ -53,7 +53,8 @@ release = '1.0'
 # ones.
 extensions = ['myst_parser',
               'sphinx.ext.autodoc',
-              'sphinx.ext.autosummary']
+              'sphinx.ext.autosummary',
+              'sphinxcontrib.mermaid']
 autodoc_member_order = 'bysource'
 
 # Add any paths that contain templates here, relative to this directory.

{django-pfx-1.4.dev16 → django-pfx-1.4.dev22}/doc/source/authentication.md

@@ -48,12 +48,50 @@ 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.
 
+### 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
+
+```bash
+pip install django-pfx[otp]
+```
+
+Then the user class must use the ```OtpUserMixin```
+
+```python
+from django.contrib.auth.models import AbstractUser
+from pfx.pfxcore.models import OtpUserMixin
+
+class MyUser(OtpUserMixin, AbstractUser):
+    pass
+```
+
+The user can then enable or disable the OTP auth using the [services documented below](#enable-mfa-otp).
+
 ## Services
 
 ### Login
 A login rest services with a `mode` parameter to choose between JWT bearer token or cookie authentication.
 In cookie mode, the JWT token is saved in an HTTP-only cookie.
 
+```{mermaid}
+
+   sequenceDiagram
+      participant App
+      participant API
+      App->>API: POST /auth/login
+      alt Authentication success
+        API->>App: 200 OK + cookie
+      else Authentication failed
+        API->>App: 401 Unautorized
+      end
+
+```
+
 **Request :** `POST` `/auth/login?mode=<mode>`
 
 **Request body:**
@@ -75,6 +113,122 @@ In cookie mode, the JWT token is saved in an HTTP-only cookie.
 | user  | the user object                        |
 
 
+### Login + TOTP
+If the user has enabled the TOTP login, the process is the same as above for the first step,
+except that the login service returns a temporary JWT token valid only for the otp services.
+
+```{mermaid}
+
+   sequenceDiagram
+      participant App
+      participant API
+      App->>API: POST /auth/login
+      alt Login success
+        API->>App: 200 OK
+        note left of API: temporary jwt token
+        App->>API: POST /auth/otp/login
+        note right of App: temporary jwt token + OTP token in body.
+        alt OTP success
+            API->>App: 200 OK
+            note left of API: JWT token in cookie or in body <br/> + user in body
+        else OTP failed
+            API->>App: 401 Unautorized
+        end
+      else Login failed
+        API->>App: 401 Unautorized
+      end
+
+```
+
+**Request :** `POST` `/auth/login?mode=<mode>`
+
+**Request body:**
+
+| Field       | Description                         |
+|-------------|-------------------------------------|
+| username    | the username                        |
+| password    | the password                        |
+| remember_me | If true, use a long validity token. |
+
+**Responses :**
+
+* `HTTP 401` if the credentials are incorrect
+* `HTTP 200` with the following body
+
+| Field | Description           |
+|-------|-----------------------|
+| token | a temporary jwt token |
+
+
+**Request :** `POST` `/auth/otp/login?mode=<mode>`
+
+**Request body:**
+
+| Field       | Description                         |
+|-------------|-------------------------------------|
+| token       | the temporary jwt token             |
+| otp         | the one time password (TOTP)        |
+
+**Responses :**
+
+* `HTTP 401` if the temporary jwt token is incorrect
+* `HTTP 403` if the otp is incorrect
+* `HTTP 200` with the following body
+
+| Field | Description                            |
+|-------|----------------------------------------|
+| token | the jwt token. (only if mode is 'jwt') |
+| user  | the user object                        |
+
+### Enable MFA OTP
+Services to enable the MFA with OTP.
+You have to call first the `activate` service to get the URI,
+encode it as a QR code and present it in the UI of your software.
+Then user then scans this QR code to add the OTP secret to his OTP App.
+Finally, the `confirm` service must be called with an OTP code retrieved
+in the OTP App to confirm the activation.
+
+**Request :** `PUT` `/auth/otp/activate`
+
+**Responses :**
+
+* `HTTP 400` if the otp is already enabled
+* `HTTP 200` with the following body
+
+| Field     | Description                           |
+|-----------|---------------------------------------|
+| setup_uri | the uri to enable the OTP application |
+
+**Request :** `PUT` `/auth/otp/confirm`
+
+**Request body:**
+
+| Field       | Description                           |
+|-------------|---------------------------------------|
+| otp_code    | the otp code retrieved in the OTP app |
+
+**Responses :**
+
+* `HTTP 422` if the otp code is invalid
+* `HTTP 200` if the otp code is valid
+
+### Disable MFA OTP
+A service to disable the MFA with OTP.
+
+**Request :** `PUT` `/auth/otp/disable`
+
+**Request body:**
+
+| Field       | Description                           |
+|-------------|---------------------------------------|
+| otp_code    | the otp code retrieved in the OTP app |
+
+**Responses :**
+
+* `HTTP 422` if the otp code is invalid
+* `HTTP 200` if the otp code is valid
+
+
 ### Logout
 A service that deletes the authentication cookie if it exists.
 

{django-pfx-1.4.dev16 → django-pfx-1.4.dev22}/pfx/pfxcore/default_settings.py

@@ -6,6 +6,10 @@ PFX_COOKIE_DOMAIN = None
 PFX_COOKIE_SECURE = True
 PFX_COOKIE_SAMESITE = 'None'
 
+PFX_LOGIN_BAN_FAILED_NUMBER = 5
+PFX_LOGIN_BAN_SECONDS_START = 60
+PFX_LOGIN_BAN_SECONDS_STEP = 60
+
 PFX_OPENAPI_PATH = "doc/api/"
 PFX_OPENAPI_FILENAME = "openapi"
 PFX_OPENAPI_TEMPLATE = {}

{django-pfx-1.4.dev16 → django-pfx-1.4.dev22}/pfx/pfxcore/middleware/authentication.py

@@ -32,25 +32,29 @@ class JWTTokenDecodeMixin:
     @classmethod
     def decode_jwt(cls, token, otp_login=False):
         try:
+            headers = jwt.get_unverified_header(token)
+            if 'pfx_user_pk' not in headers:
+                raise jwt.InvalidTokenError(
+                    "Missing pfx_user_pk in token headers")
+            user = cls.get_cached_user(headers['pfx_user_pk'])
             decoded = jwt.decode(
-                token, settings.PFX_SECRET_KEY,
+                token,
+                user.get_user_jwt_signature_key() + settings.PFX_SECRET_KEY,
                 options=dict(require=["exp"]),
                 algorithms="HS256")
-            user = cls.get_cached_user(decoded['pfx_user_pk'])
             if 'otp_login' in decoded:
                 if otp_login:
                     return user, *decoded['otp_login']
                 raise jwt.InvalidTokenError(
                     "This token is reserved for OTP login")
             return user
-        except get_user_model().DoesNotExist:
-            raise
-        except DecodeError as e:
-            logger.exception(e)
-            raise
-        except jwt.ExpiredSignatureError:
+        except (get_user_model().DoesNotExist, jwt.ExpiredSignatureError,
+                jwt.InvalidTokenError, jwt.InvalidSignatureError) as e:
+            # Log these exceptions only in debug mode
+            logger.debug(e, exc_info=True)
             raise
-        except Exception as e:  # pragma: no cover
+        except (DecodeError, Exception) as e:
+            # Always logs unexpected exceptions
             logger.exception(e)
             raise
 

{django-pfx-1.4.dev16 → django-pfx-1.4.dev22}/pfx/pfxcore/models/__init__.py

@@ -1,4 +1,6 @@
+from .abstract_pfx_base_user import AbstractPFXBaseUser
 from .cache_mixins import CacheableMixin, CacheDependsMixin
+from .login_ban import LoginBan
 from .not_null_fields import (
     NotNullCharField,
     NotNullTextField,

django-pfx-1.4.dev22/pfx/pfxcore/models/abstract_pfx_base_user.py

@@ -0,0 +1,15 @@
+from django.contrib.auth.models import AbstractBaseUser
+
+
+class AbstractPFXBaseUser(AbstractBaseUser):
+    class Meta:
+        abstract = True
+
+    def get_user_jwt_signature_key(self):
+        """
+        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.
+        """
+        return self.password

django-pfx-1.4.dev22/pfx/pfxcore/models/login_ban.py

@@ -0,0 +1,60 @@
+from datetime import timedelta
+
+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()
+
+
+class LoginBanQuerySet(models.QuerySet):
+    def is_ban(self, username):
+        if not username or settings.PFX_LOGIN_BAN_FAILED_NUMBER == 0:
+            return False
+        try:
+            ban = self.get(username=username)
+        except LoginBan.DoesNotExist:
+            return False
+        if ban.failed_counter % settings.PFX_LOGIN_BAN_FAILED_NUMBER == 0:
+            seconds = settings.PFX_LOGIN_BAN_SECONDS_START + (
+                settings.PFX_LOGIN_BAN_SECONDS_STEP * (ban.failed_counter - 1))
+            ban_time = ban.last_failed + timedelta(seconds=seconds)
+            now = timezone.now()
+            if now < ban_time:
+                return ban_time - now
+        return False
+
+    def ban(self, username):
+        if not username:
+            return
+        try:
+            ban = self.get(username=username)
+            ban.save()
+        except LoginBan.DoesNotExist:
+            LoginBan.objects.create(username=username)
+
+    def unban(self, username):
+        if not username:
+            return
+        self.filter(username=username).delete()
+
+
+class LoginBan(models.Model):
+    username = models.CharField(_("Username"), max_length=150, unique=True)
+    failed_counter = models.IntegerField(_("Failed counter"))
+    last_failed = models.DateTimeField(_("Last failed"), auto_now=True)
+
+    objects = LoginBanQuerySet.as_manager()
+
+    class Meta:
+        verbose_name = _("Login ban")
+        verbose_name_plural = _("Login bans")
+
+    def __str__(self):
+        return self.username
+
+    def save(self, *args, **kwargs):
+        self.failed_counter = (self.failed_counter or 0) + 1
+        return super().save(*args, **kwargs)

{django-pfx-1.4.dev16 → django-pfx-1.4.dev22}/pfx/pfxcore/models/otp_user_mixin.py

@@ -42,3 +42,7 @@ class OtpUserMixin(models.Model):
         import pyotp
         totp = pyotp.parse_uri(self.get_otp_setup_uri(tmp=tmp))
         return totp.verify(otp_code)
+
+    def get_user_jwt_signature_key(self):
+        return super().get_user_jwt_signature_key() + (
+            self.otp_secret_token or "")

{django-pfx-1.4.dev16 → django-pfx-1.4.dev22}/pfx/pfxcore/views/authentication_views.py

@@ -31,6 +31,7 @@ from pfx.pfxcore.exceptions import (
 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.shortcuts import delete_token_cookie
 
@@ -71,6 +72,19 @@ class AuthenticationView(
         Can be overridden to customize the error."""
         raise AuthenticationError()
 
+    def login_ban_response(self, ban_dt):
+        """Return the response for login temporary ban.
+
+        Can be overridden to customize the error."""
+        seconds = int(ban_dt.total_seconds())
+        response = JsonResponse(dict(
+            message=_(
+                "Your connection is temporarily disabled after several "
+                "unsuccessful attempts, please retry in {seconds} seconds."
+            ).format(seconds=seconds)), status=429)
+        response['Retry-after'] = seconds
+        return response
+
     @method_decorator(sensitive_post_parameters())
     @method_decorator(never_cache)
     @rest_api(
@@ -115,14 +129,23 @@ class AuthenticationView(
             responses:
                 422:
                     description: The credentials are not valid.
+                429:
+                    description: Temporary banned after several unsuccessful
+                        attempts.
         """
         data = self.deserialize_body()
-        user = authenticate(self.request, username=data.get('username'),
+        username = data.get('username')
+        ban_dt = LoginBan.objects.is_ban(username)
+        if ban_dt:
+            return self.login_ban_response(ban_dt)
+        user = authenticate(self.request, username=username,
                             password=data.get('password'))
         if isinstance(user, CacheableMixin):
             user.cache_delete()
         if user is None:
+            LoginBan.objects.ban(username)
             return self.login_failed_response()
+        LoginBan.objects.unban(username)
         mode = self.request.GET.get('mode', 'jwt')
         remember_me = data.get('remember_me', False)
         if isinstance(user, OtpUserMixin) and user.otp_secret_token:
@@ -233,17 +256,22 @@ class AuthenticationView(
     def _prepare_token(self, user, validity, **extra_payload):
         exp = datetime.now(tz=timezone.utc) + validity
         payload = dict(
-            pfx_user_pk=user.pk, exp=exp,
+            exp=exp,
             **self.get_extra_payload(user), **extra_payload)
         return jwt.encode(
-            payload, settings.PFX_SECRET_KEY, algorithm="HS256")
+            payload,
+            user.get_user_jwt_signature_key() + settings.PFX_SECRET_KEY,
+            headers=dict(
+                pfx_user_pk=user.pk,
+                username=user.get_username()),
+            algorithm="HS256")
 
     def get_extra_payload(self, user):
         """Get extra payload for user token.
 
         By default, there is only one private claim in the JWT token
-        (the user PK : pfx_user_pk). This method can be overridden
-        to add claims (key:value attributes) to the JWT token.
+        (exp : expiration). This method can be overridden
+        to add claims (key: value attributes) to the JWT token.
 
         :param user: The user
         :returns: The extra payload
@@ -371,6 +399,7 @@ class AuthenticationView(
                 user.set_password(data['password'])
                 user.is_active = True
                 user.save()
+                user.refresh_from_db()
                 if 'autologin' in data and data['autologin'] in (
                         'jwt', 'cookie'):
                     return self._login_success(user, data['autologin'])
@@ -521,6 +550,9 @@ class AuthenticationView(
             responses:
                 422:
                     description: If OTP code is missing, invalid or expired.
+                429:
+                    description: Temporary banned after several unsuccessful
+                        attempts.
                 401:
                     description: If the token is missing, invalid or expired.
                 403:
@@ -528,9 +560,13 @@ class AuthenticationView(
 
         """
         data = self.deserialize_body()
+        token = data.get('token')
+        username = jwt.get_unverified_header(token).get('username')
+        ban_dt = LoginBan.objects.is_ban(username)
+        if ban_dt:
+            return self.login_ban_response(ban_dt)
         try:
-            user, mode, remember_me = self.decode_jwt(
-                data.get('token'), otp_login=True)
+            user, mode, remember_me = self.decode_jwt(token, otp_login=True)
         except Exception:
             raise UnauthorizedError()
         if not isinstance(user, OtpUserMixin):
@@ -539,7 +575,9 @@ class AuthenticationView(
         if not user.otp_secret_token:
             raise ForbiddenError()
         if user.is_otp_valid(data.get('otp_code')):
+            LoginBan.objects.unban(username)
             return self._login_success(user, mode, remember_me)
+        LoginBan.objects.ban(username)
         return self.login_failed_response()
 
     def get_user(self, uidb64):

{django-pfx-1.4.dev16 → django-pfx-1.4.dev22}/requirements.txt

@@ -14,6 +14,7 @@ apispec
 sphinx
 myst-parser
 sphinx-rtd-theme
+sphinxcontrib-mermaid
 dill
 apispec
 pyyaml

{django-pfx-1.4.dev16 → django-pfx-1.4.dev22}/tests/models.py

@@ -1,4 +1,4 @@
-from django.contrib.auth.base_user import AbstractBaseUser, BaseUserManager
+from django.contrib.auth.base_user import BaseUserManager
 from django.core.mail import send_mail
 from django.db import models
 from django.utils.functional import cached_property
@@ -7,6 +7,7 @@ from django.utils.translation import gettext_lazy as _
 from pfx.pfxcore.decorator import rest_property
 from pfx.pfxcore.fields import MediaField, MinutesDurationField
 from pfx.pfxcore.models import (
+    AbstractPFXBaseUser,
     CacheableMixin,
     CacheDependsMixin,
     JSONReprMixin,
@@ -48,7 +49,7 @@ class UserManager(BaseUserManager):
             is_superuser=True)
 
 
-class User(CacheableMixin, JSONReprMixin, OtpUserMixin, AbstractBaseUser):
+class User(CacheableMixin, JSONReprMixin, OtpUserMixin, AbstractPFXBaseUser):
     username = models.CharField(
         'username',
         max_length=150,