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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-pfx
-Version: 1.4.dev16
+Version: 1.4.dev18
 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.dev18}/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.dev18}/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.dev18}/requirements.txt

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