tomtoolkit 3.0.1__tar.gz → 3.1.0__tar.gz

tomtoolkit-3.1.0/.git/FETCH_HEAD

@@ -0,0 +1 @@
+e6496469648b1bed1ff52bb70cbdc82f9206c588		'e6496469648b1bed1ff52bb70cbdc82f9206c588' of https://github.com/TOMToolkit/tom_base

tomtoolkit-3.1.0/.git/HEAD

@@ -0,0 +1 @@
+e6496469648b1bed1ff52bb70cbdc82f9206c588

tomtoolkit-3.1.0/.git/config

@@ -0,0 +1,12 @@
+[core]
+	repositoryformatversion = 0
+	filemode = true
+	bare = false
+	logallrefupdates = true
+[remote "origin"]
+	url = https://github.com/TOMToolkit/tom_base
+	fetch = +refs/heads/*:refs/remotes/origin/*
+[gc]
+	auto = 0
+[http "https://github.com/"]
+	extraheader = AUTHORIZATION: basic eC1hY2Nlc3MtdG9rZW46Z2hzXzE1MzY4X2V5SmhiR2NpT2lKRlV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpoZFdRaU9pSmhkWFJvYm1RaUxDSmpkSGdpT2lKZlUxSTBlbUZpYkZBMGFGYzFSVTVTVG10UldITXhibXA2Y1hneFFuSmpTblF0YkhkUk1uRlliRUp4WkZadVgwcG1ibEprU1ZKUklpd2laWGh3SWpveE56a3dNamc1T0RBeExDSnBZWFFpT2pFM09UQXlPRFl5TURFc0ltbHpjeUk2SW1kcGRHaDFZaUlzSW1wMGFTSTZJbVF6WmpjMVpETmlMV1JoWWpVdE5HUTRPUzA1WXpabExXUXpPR0kxTTJZMk0yTXdaaUlzSW5abGNpSTZNMzAuWm1PcklVTm1qWlNHNkZLU0hIMUZCeldOUzV1MzdyZ0RsN0c0VmJPMVhrR2JMNVNBdHVKWGRxQjJNUXJEUGFGM3V2RldYQ2VwLUxyMjRkRnRwLVQ5RVE=

tomtoolkit-3.1.0/.git/logs/HEAD

@@ -0,0 +1 @@
+0000000000000000000000000000000000000000 e6496469648b1bed1ff52bb70cbdc82f9206c588 runner <runner@runnervmtr4k5.qmfuewowp3wexnqqdqohoyuc0d.yx.internal.cloudapp.net> 1790286206 +0000	checkout: moving from master to refs/tags/3.1.0

tomtoolkit-3.1.0/.git/refs/tags/3.1.0

@@ -0,0 +1 @@
+e6496469648b1bed1ff52bb70cbdc82f9206c588

tomtoolkit-3.1.0/.git/shallow

@@ -0,0 +1 @@
+e6496469648b1bed1ff52bb70cbdc82f9206c588

{tomtoolkit-3.0.1 → tomtoolkit-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tomtoolkit
-Version: 3.0.1
+Version: 3.1.0
 Summary: TOM Toolkit and base modules
 License-Expression: GPL-3.0-only
 License-File: LICENSE
@@ -31,6 +31,7 @@ Requires-Dist: beautifulsoup4 (<5)
 Requires-Dist: crispy-bootstrap5 (<2027)
 Requires-Dist: cryptography (<=50.0.0)
 Requires-Dist: django (>=5.2.17,<6)
+Requires-Dist: django-allauth[mfa] (>=65.19.4,<66)
 Requires-Dist: django-bootstrap5 (<27)
 Requires-Dist: django-contrib-comments (>=2.0,<3.0)
 Requires-Dist: django-crispy-forms (>=2.7,<3.0)

tomtoolkit-3.1.0/docs/Makefile

@@ -0,0 +1,40 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# this rule builds a single file and is used by the watch rule (below).
+html-file:
+	@test -n "$(FILE)" || { echo "usage: make html-file FILE=path/to/page.rst"; exit 1; }
+	@$(SPHINXBUILD) -b html -d "$(BUILDDIR)/doctrees" "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O) "$(FILE)"
+
+# type 'make watch' to build files as they are saved
+watch:
+	@echo "Watching $(SOURCEDIR) for changes to .rst and .md files; Ctrl-C to stop."
+	@inotifywait -m -r -q -e close_write,moved_to --format '%w%f' --include '\.(rst|md)$$' \
+	    "$(SOURCEDIR)" "@$(SOURCEDIR)/$(BUILDDIR)" \
+	| while read -r changed; do \
+	    echo "==> $$changed"; \
+	    $(MAKE) --no-print-directory html-file FILE="$$changed"; \
+	done
+
+# Here's how do that (i.e. 'make watch') from the CLI not using make:
+#
+#     inotifywait -m -r -q -e close_write,moved_to --format '%w%f' --include '\.(rst|md)$' . @./_build \
+#         | while read -r changed; do make html-file FILE="$changed"; done
+
+.PHONY: help html-file watch Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

tomtoolkit-3.1.0/docs/common/authentication.rst

@@ -0,0 +1,361 @@
+Accounts and Authentication
+===========================
+
+.. Note::
+
+    This page describes the accounts and authentication features introduced in TOM Toolkit 3.1. If you are
+    upgrading an existing TOM, see :doc:`Updating your TOM <../introduction/updating>`.
+
+TOM Toolkit builds its user accounts on Django's ``django.contrib.auth`` and on
+`django-allauth <https://docs.allauth.org/en/latest/>`_, the de-facto standard Django package for login,
+registration, password management and multi-factor authentication. Out of the box, your TOM behaves the way
+users expect from any modern web application:
+
+- users log in with a username and password and may enable **two-factor authentication** (an authenticator app
+  plus recovery codes) from their profile page;
+- administrators create accounts, or you can enable **self-registration** (open, or requiring administrator
+  approval);
+- users change their own password; when an email backend is configured, you can also offer
+  **password reset by email**;
+- every user has a personal **API token** for scripted access.
+
+Anything more strict than those defaults is switched on by configuration settings: requiring two-factor
+authentication, password composition rules and expiry, a terms-of-service agreement, mandatory profile fields,
+and API-token expiry. Each control is general; how you combine them is up to your project's policy. Example
+combinations are collected in :doc:`Common accounts scenarios <authentication_scenarios>`.
+
+
+Creating accounts and self-registration
+---------------------------------------
+
+By default only superusers create accounts (*Users* → *Add user*). To let people register
+themselves, set ``TOM_REGISTRATION_STRATEGY`` in ``settings.py``:
+
+``None`` (default)
+    No self-registration. ``/accounts/signup/`` shows a "registration is closed" page inviting the visitor to
+    contact the TOM's administrators for an account.
+
+``'open'``
+    Visitors fill in the sign-up form and are logged in immediately. New users are added to the ``Public`` group.
+
+``'approval_required'``
+    Visitors fill in the sign-up form; the account is created **inactive** and added to the ``Public`` group. A
+    superuser approves it from the *Pending users* table on the *Users* page (``/users/``). Until then the user sees
+    an "account pending approval" page when they try to log in. If an email backend is configured, the addresses in
+    ``settings.MANAGERS`` are notified of each request and the user is notified when approved (templates
+    ``account/email/registration_requested_*.txt`` and ``account/email/registration_approved_*.txt``; sender
+    ``DEFAULT_FROM_EMAIL``).
+
+    A working email backend is effectively a prerequisite for a smooth ``'approval_required'`` flow. Without one
+    the flow still works, but nobody is notified of anything: the *Pending users* table makes this explicit and
+    the approver is instructed to inform the user directly. Additionally, ``manage.py check`` warns
+    of this (no email) situation (``tom_common.W002``). See :doc:`Email configuration <email_configuration>`.
+
+The sign-up form prompts for username, email, password, first and last name, organization/affiliation and
+phone number; only fields listed in ``TOM_REQUIRED_USER_FIELDS`` are required, any others are optional.
+When a terms-of-service version is configured the form also requires the
+*I accept the terms of service* checkbox (see :ref:`auth-terms`).
+
+A *Register* button appears in the navbar and a link on the login page whenever registration is open.
+
+.. Note::
+
+    In TOM Toolkit 3.1, ``TOM_REGISTRATION_STRATEGY`` replaces the ``tom_registration`` plugin, which is
+    deprecated. See :doc:`Updating your TOM <../introduction/updating>` for the mapping from ``tom_registration``'s
+    settings, URL names and templates to their replacements.
+
+Customizing registration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Every piece of registration behavior follows the same pattern: tom_base ships a default implementation (a form,
+an adapter method, a template), and a setting names the implementation to use. To change a behavior, subclass
+the default in your TOM's ``custom_code`` app (or drop a template into your TOM's ``templates/`` directory) and
+point the setting at your version in ``settings.py``.
+
+- **Extra sign-up fields**: subclass ``tom_common.accounts.forms.TomSignupForm`` in your ``custom_code`` app,
+  add fields, and store them in ``signup(self, request, user)``; point django-allauth at it with
+  ``ACCOUNT_SIGNUP_FORM_CLASS = 'custom_code.forms.MySignupForm'``.
+- **Sign-up Behavior** (who may sign up, which group new users join, notification emails, redirects): subclass
+  ``tom_common.accounts.adapters.TomAccountAdapter`` and set, for example,
+  ``ACCOUNT_ADAPTER = 'custom_code.adapters.MyAccountAdapter'``.
+  See `Adapter <https://docs.allauth.org/en/latest/account/adapter.html>`_ for the available hooks.
+- **Templates**: ``account/signup.html``, ``account/signup_closed.html``, ``account/account_inactive.html`` and the
+  email templates above can be overridden in your TOM's ``templates/`` directory. (This is the ``templates/``
+  directory at the top level of your TOM, sibling to your ``manage.py`` module).
+
+
+Two-factor authentication
+-------------------------
+
+Two-factor authentication (2FA, also called multi-factor authentication or MFA) uses a **time-based one-time
+password** (TOTP) from an authenticator app. Microsoft Authenticator, Google Authenticator, Authy, 1Password,
+Bitwarden and similar all work. A set of **recovery codes** is supplied for when an authenticator app is unavailable.
+
+2FA From the User's Perspective
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Open your profile (click on your name in the navbar → *Profile*) and click *Enable two-factor authentication*
+   on the *Security* card (or go to ``/accounts/2fa/``).
+2. Scan the QR code with your authenticator app (or type the key shown below it), then enter the 6-digit code the
+   authenticator app displays.
+3. Save the recovery codes. Each code can be used one time in place of an app code. By default, a new set of
+   recovery codes is available from the *Security* card of your profile page.
+
+From then on, login asks for a code after the password. The *Security* card shows whether 2FA is enabled and links
+to the two-factor management page, where you can view, download, or regenerate your recovery codes, or disable the
+app. Sensitive actions (changing 2FA settings, regenerating an API token when required) ask you to confirm your
+password or a code again if your last login was more than a few minutes ago.
+
+If you lose both the app and the recovery codes, an administrator can reset your authenticator in the Django admin
+page (*Multi-factor authentication* → *Authenticators*) and you then can enroll again.
+
+From the TOM developer's Perspective
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+2FA is always available to every user and is optional by default. To require it, set::
+
+    TOM_MFA_REQUIRED = 'all'  # or 'superusers' to require it only for privileged users
+
+After login, users who have not yet enabled 2FA are taken to the enrollment page and cannot use the rest of
+the TOM until 2FA enabled. When ``TOM_MFA_REQUIRED = 'all'``, ``'all'`` means every user including superusers
+(and to social/SSO logins if you configure them); the default, ``None``, means 2FA is optional.
+When ``TOM_MFA_REQUIRED`` is set, users cannot disable their authenticator app (but an administrator can still
+reset it).
+
+Other django-allauth MFA settings (``MFA_SUPPORTED_TYPES``, ``MFA_TOTP_TOLERANCE``, ``MFA_RECOVERY_CODE_COUNT`` …)
+can be set in ``settings.py``; see `MFA configuration <https://docs.allauth.org/en/latest/mfa/configuration.html>`_.
+TOM Toolkit enables TOTP and recovery codes; passkeys/WebAuthn are not enabled (contact us if you need this).
+
+
+Passwords
+---------
+
+Users can change their password on their profile edit page (``/users/<id>/update/``) or at
+``/accounts/password/change/``. Superusers can set another user's password from the *Users* page; a password set
+this way must be changed by the user at their next login when password expiry is enabled.
+
+Password constraints
+~~~~~~~~~~~~~~~~~~~~
+
+By default, password constraits are Django's ``AUTH_PASSWORD_VALIDATORS``.
+TOM Toolkit adds two validators you can include:
+
+``tom_common.accounts.password_validation.CharacterClassValidator``
+    Requires at least one upper-case letter, one lower-case letter, one digit and one special character.
+
+``tom_common.accounts.password_validation.NotSameAsCurrentPasswordValidator``
+    Rejects a "new" password identical to the current one (useful together with expiry).
+
+For example, a policy of 12+ characters with all four character classes, different from the user's name and email::
+
+    AUTH_PASSWORD_VALIDATORS = [
+        {'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator'},
+        {'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
+         'OPTIONS': {'min_length': 12}
+        },
+        {'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator'},
+        {'NAME': 'tom_common.accounts.password_validation.CharacterClassValidator'},
+        {'NAME': 'tom_common.accounts.password_validation.NotSameAsCurrentPasswordValidator'},
+    ]
+
+You can write your own validator class in ``custom_code`` and list it the same way (see
+`Django password validation <https://docs.djangoproject.com/en/stable/topics/auth/passwords/#password-validation>`_).
+
+.. Note::
+
+    Current guidance (NIST SP 800-63B) favours long passphrases and multi-factor authentication over password composition
+    rules and periodic expiry. TOM Toolkit provides the capabilities to implement your specific hosting policy requirements.
+
+Password expiry
+~~~~~~~~~~~~~~~
+
+::
+
+    TOM_PASSWORD_EXPIRY_DAYS = 60    # default None (never expires)
+
+When set, a user whose password is older than this is redirected to the change-password page after login (and on
+any later request) until they change it. The age is counted from the last change; a password set by an
+administrator counts as expired. When you first enable expiry, passwords last changed before the upgrade are
+treated as old, so most existing users are asked to change their password once.
+
+Password reset by email
+~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    TOM_PASSWORD_RESET_ENABLED = True    # default False
+
+Adds a *Forgot your password?* link to the login page and enables django-allauth's reset-by-email flow. This
+requires a working email configuration (see :doc:`Email configuration <email_configuration>`). When it is off the reset pages
+are not served at all, so a TOM without email cannot leak "unknown account" mails or error on them.
+
+
+.. _auth-terms:
+
+Terms of service
+----------------
+
+::
+
+    TOM_TERMS_OF_SERVICE_VERSION = '2026-09-01'    # default None (no terms)
+
+When set, every user must accept the current terms before using the TOM: new users tick a checkbox on the sign-up
+form; existing users (and users created by an administrator) are shown the terms right after logging in and must
+accept them. Acceptances are recorded with the version, time and IP address. To update your terms,
+**change the version string** and users will be prompted to accept the updated terms.
+
+Write your terms in the template ``tom_common/partials/terms_of_service_text.html`` in your TOM's ``templates/``
+directory (plain HTML). They are shown at the ``/terms/`` page and on the acceptance page.
+
+
+.. _auth-profile-fields:
+
+Profile fields
+--------------
+
+In addition to Django's first name, last name and email, TOM Toolkit adds *organization / affiliation* and *phone number*
+fields to a user's profile. To make any of these mandatory, add them to ``TOM_REQUIRED_USER_FIELDS``::
+
+    TOM_REQUIRED_USER_FIELDS = ['first_name', 'last_name', 'email']    # default []
+
+Required fields are enforced on the sign-up form and the user edit form, and a logged-in user whose profile is
+missing a required field is redirected to their profile edit page until it is complete.
+
+Projects that need more profile fields add their own model in ``custom_code`` and show it on the profile page with
+the ``profile_details()`` integration point (see :doc:`Customizing templates <../customization/customize_templates>`).
+
+
+API access
+----------
+
+Every user has a personal API token, shown on their profile and regenerable from their profile edit page; see
+:doc:`Accessing data through the REST API <../managing_data/accessing_data_through_REST_API>`. Two settings
+can customize API access::
+
+    TOM_API_TOKEN_EXPIRY_DAYS = 60        # default None: tokens do not expire
+    TOM_API_TOKEN_REQUIRES_MFA = True     # default False
+
+- With an expiry, requests with a token older than the limit are rejected (HTTP 401 with an explanatory message);
+  the user regenerates the token on their edit page, which shows when it was created and when it expires.
+- With ``TOM_API_TOKEN_REQUIRES_MFA``: the password-only ``/api/token-auth/`` endpoint is disabled (because this
+  would by-pass the second factor).
+
+Both are enforced by ``tom_common.accounts.api_auth.TomTokenAuthentication``, which replaces the plain REST framework
+``TokenAuthentication`` in ``REST_FRAMEWORK``::
+
+    REST_FRAMEWORK = {
+        'DEFAULT_AUTHENTICATION_CLASSES': [
+            'tom_common.accounts.api_auth.TomTokenAuthentication',   # Authorization: Token <key>
+            'rest_framework.authentication.SessionAuthentication',   # logged-in browsers
+            # 'rest_framework.authentication.BasicAuthentication',   # username/password per request; omit this when
+                                                                     # you require two-factor authentication
+        ],
+        ...
+    }
+
+Browser sessions (``SessionAuthentication``) are protected by the normal login, including 2FA.
+
+.. Note::
+
+    TOM-to-TOM data sharing (``DATA_SHARING``) currently authenticates with the destination's username and
+    password (HTTP Basic). A destination that turns off ``BasicAuthentication`` must give its partners tokens
+    instead; support for ``API_TOKEN`` in ``DATA_SHARING`` is planned.
+
+
+Access strategy and open URLs
+-----------------------------
+
+With ``AUTH_STRATEGY = 'LOCKED'`` the login, sign-up, second-factor, pending-approval and (when enabled) password
+reset pages are open automatically. They are to ``OPEN_URLS`` to enable the authorization process. As before,
+``/api/`` paths that scripts reach with a token must be listed in ``OPEN_URLS``.
+
+
+Customizing the authentication pages and behaviour
+--------------------------------------------------
+
+Everything below is done in your TOM (``settings.py``, ``templates/``, ``custom_code``); nothing in tom_base
+needs to change.
+
+Templates
+    The account pages are django-allauth templates rendered inside your TOM's ``tom_common/base.html``. To restyle
+    all of them at once, override ``allauth/layouts/base.html`` and the small element templates under
+    ``allauth/elements/`` (TOM Toolkit ships Bootstrap 5 versions of ``fields``, ``field``, ``button``,
+    ``button_group`` and ``panel``). To change one page, override its template (``account/login.html``,
+    ``account/signup.html``, ``mfa/index.html`` …). Template names are listed in the
+    `django-allauth template documentation <https://docs.allauth.org/en/latest/common/templates.html>`_.
+Forms
+    ``ACCOUNT_FORMS = {'login': 'custom_code.forms.MyLoginForm'}`` (and ``signup``, ``change_password`` …)
+    replace individual forms; ``MFA_FORMS`` does the same for the 2FA forms. See
+    `Forms <https://docs.allauth.org/en/latest/account/forms.html>`_.
+Adapters
+    ``ACCOUNT_ADAPTER`` (default ``tom_common.accounts.adapters.TomAccountAdapter``) controls registration, redirects,
+    email sending and the inactive-account response; ``MFA_ADAPTER`` (default ``tom_common.accounts.adapters.TomMFAAdapter``)
+    controls the issuer name, secret encryption and whether users may remove their authenticator. Subclass the
+    TOM Toolkit adapter and override the hook you need.
+Password validators
+    ``AUTH_PASSWORD_VALIDATORS`` (see above).
+Post-login requirements
+    ``TOM_ACCOUNT_REQUIREMENTS`` is the ordered list of checks run for every logged-in request::
+
+        TOM_ACCOUNT_REQUIREMENTS = [
+            'tom_common.accounts.requirements.terms_of_service_accepted',
+            'tom_common.accounts.requirements.mfa_enrolled',
+            'tom_common.accounts.requirements.password_not_expired',
+            'tom_common.accounts.requirements.required_fields_present',
+        ]
+
+    Each built-in check is a function whose companion ``TOM_*`` setting is its parameter: unconfigured means the
+    check does nothing. Every *configured* requirement also appears as a column on the *Users* page, so
+    administrators can see it's status at a glace.
+    
+    To add your own: Define a function taking the request and
+    returning ``None`` (meaning the requirement is met) or, if the requirement is not met, the URL name of the
+    page that the user should be directed to in order to meet the requirement.
+    Alternatively, to also get a *Users*-page column, create a subclass
+    ``tom_common.accounts.requirements.AccountRequirement``. Define ``label``, ``is_configured()`` and
+    ``is_met(user)``. To pass configuration values, define it its own ``settings.py`` value
+    following the same inactive-unless-configured pattern. The pages you return are exempt from the
+    check automatically (presumably, they need to be accessed to meet the requirement), as are logout,
+    the account pages and static files. Requests from scripts using a token are not subject to these checks
+    (see API access above).
+Social / single sign-on
+    django-allauth's ``socialaccount`` app (ORCID, GitHub, Google, OpenID Connect providers …) can be added to a
+    TOM alongside the TOM Toolkit integration; social logins go through the same second-factor and post-login
+    checks. TOM Toolkit does not configure any provider for you; see
+    `Social account <https://docs.allauth.org/en/latest/socialaccount/index.html>`_.
+
+
+.. _auth-deployment-notes:
+
+Deployment notes
+----------------
+
+- **Cache**: login rate limits and one-time-code replay protection are stored in Django's ``CACHES``. The default
+  file cache in a temporary directory is per machine; if your TOM runs several processes on different hosts (or
+  containers), use a shared cache (database cache, Redis, Memcached).
+- **Reverse proxies**: django-allauth does not trust ``X-Forwarded-For`` unless you set
+  ``ALLAUTH_TRUSTED_PROXY_COUNT`` to the number of proxies in front of your TOM; otherwise all users share the
+  proxy's IP for rate limiting and in terms-of-service records.
+- **Sessions**: consider ``SESSION_COOKIE_AGE``, ``SESSION_SAVE_EVERY_REQUEST`` (idle timeout),
+  ``SESSION_EXPIRE_AT_BROWSER_CLOSE``, ``SESSION_COOKIE_SECURE``/``CSRF_COOKIE_SECURE`` and
+  ``ACCOUNT_SESSION_REMEMBER = False`` (hide "Remember me") for stricter environments. See
+  :doc:`Deployment tips <../deployment/deployment_tips>`.
+- **Email**: self-registration notifications, password reset and any django-allauth email feature need a working
+  ``EMAIL_BACKEND``; sender addresses come from ``DEFAULT_FROM_EMAIL`` and ``SERVER_EMAIL``; subjects are prefixed
+  with your ``TOM_NAME``. ``manage.py check`` warns (``tom_common.W002``) when approval-required registration or
+  password reset is enabled without an email backend; if email cannot be sent, the user or the approver
+  is instead informed of this in the UI.
+- **Security log**: login success/failure, logout, password changes, two-factor enrolment/removal, API-token
+  regeneration and terms acceptance are logged to the ``tom_common.security`` logger at ``INFO``. Route it to a
+  file or your log collector in ``LOGGING``.
+- **Site**: django-allauth uses ``django.contrib.sites``; keep ``SITE_ID`` in your settings (it is there by default).
+
+
+Settings reference
+------------------
+
+All settings introduced on this page are documented in :doc:`Custom settings <customsettings>`:
+``TOM_REGISTRATION_STRATEGY``, ``TOM_MFA_REQUIRED``, ``TOM_PASSWORD_EXPIRY_DAYS``, ``TOM_PASSWORD_RESET_ENABLED``,
+``TOM_TERMS_OF_SERVICE_VERSION``, ``TOM_REQUIRED_USER_FIELDS``, ``TOM_API_TOKEN_EXPIRY_DAYS``,
+``TOM_API_TOKEN_REQUIRES_MFA``, ``TOM_ACCOUNT_REQUIREMENTS``. django-allauth's own settings (``ACCOUNT_*``,
+``MFA_*``) are documented at `docs.allauth.org <https://docs.allauth.org/en/latest/>`_.

tomtoolkit-3.1.0/docs/common/authentication_scenarios.rst

@@ -0,0 +1,92 @@
+Common Accounts Scenarios
+=========================
+
+Three worked configurations combining the controls from :doc:`Accounts and Authentication
+<authentication>`. Each shows the complete ``settings.py`` recipe and what your users
+experience. Settings not shown keep their defaults; settings are documented in
+:doc:`Custom settings <customsettings>`.
+
+A public TOM with optional two-factor authentication
+----------------------------------------------------
+
+This is the out-of-the-box configuration. For a TOM whose pages are public
+(the default ``READ_ONLY`` strategy) and whose collaborators get accounts from an
+administrator:
+
+.. code-block:: python
+
+    # settings.py: no changes. (This is the default behavior).
+
+What you get: anonymous visitors browse but cannot change anything; administrators create
+accounts from the *Users* page; every user *may* enable two-factor authentication from the
+*Security* card on their profile page. The *Users* page shows who has MFA enabled. To require
+MFA on privileged accounts while leaving it optional otherwise::
+
+    TOM_MFA_REQUIRED = 'superusers'  # MFA required for privileged users; optional otherwise.
+
+A locked TOM with self-registration
+-----------------------------------
+
+For a TOM serving a collaboration whose data is private, but whose number of users is large
+enough that administrators should not create every account by hand. Users register themselves
+and an administrator approves each one.
+
+.. code-block:: python
+
+    AUTH_STRATEGY = 'LOCKED'
+    TOM_REGISTRATION_STRATEGY = 'approval_required'
+    TOM_PASSWORD_RESET_ENABLED = True
+    TOM_REQUIRED_USER_FIELDS = ['first_name', 'last_name', 'email', 'affiliation']
+
+    # the notifications this flow sends need working email:
+    EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'
+    EMAIL_HOST = os.environ['EMAIL_HOST']          # and EMAIL_PORT, EMAIL_USE_TLS, credentials
+    DEFAULT_FROM_EMAIL = SERVER_EMAIL = os.environ['DEFAULT_FROM_EMAIL']
+    MANAGERS = [('TOM administrators', os.environ['TOM_ADMIN_EMAIL'])]
+
+What you get: every TOM page requires login (except for pages required for registration).
+A *Register* button is placed in the navbar; applicants fill
+in the required fields, wait on the "pending approval" page, and ``MANAGERS`` are emailed;
+an administrator approves the registration request from the *Pending users* table and the
+new user is emailed a login link. Without working email, the flow still works, but you
+must tell applicants yourself. ``manage.py check`` warns of this (no email) situation.
+
+A strict hosting policy
+-----------------------
+
+For a TOM with mandatory two-factor authentication, password composition and expiry rules,
+terms-of-service acceptance, and API-token controls. 
+
+.. code-block:: python
+
+    TOM_MFA_REQUIRED = 'all'
+    TOM_PASSWORD_EXPIRY_DAYS = 60
+    TOM_TERMS_OF_SERVICE_VERSION = '2026-09-01'    # bump the string to require re-acceptance
+    TOM_REQUIRED_USER_FIELDS = ['first_name', 'last_name', 'email', 'affiliation', 'phone_number']
+    TOM_API_TOKEN_EXPIRY_DAYS = 60
+    TOM_API_TOKEN_REQUIRES_MFA = True
+
+    AUTH_PASSWORD_VALIDATORS = [
+        {'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator'},
+        {'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator', 'OPTIONS': {'min_length': 12}},
+        {'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator'},
+        {'NAME': 'tom_common.accounts.password_validation.CharacterClassValidator'},
+        {'NAME': 'tom_common.accounts.password_validation.NotSameAsCurrentPasswordValidator'},
+    ]
+
+    REST_FRAMEWORK = {
+        'DEFAULT_AUTHENTICATION_CLASSES': [
+            'tom_common.accounts.api_auth.TomTokenAuthentication',  # API token requires MFA enabled
+            'rest_framework.authentication.SessionAuthentication',
+            # no BasicAuthentication: per-request passwords would bypass the second factor
+        ],
+        'DEFAULT_PERMISSION_CLASSES': ['rest_framework.permissions.IsAuthenticated'],
+    }
+
+Write your terms of service in ``templates/tom_common/partials/terms_of_service_text.html``.
+(This is the ``templates`` directory at the top level of your TOM, sibling to your
+``manage.py`` module).
+
+What you get: after logging in, every user is walked through accepting the terms,
+enrolling an authenticator app, replacing an expired (or administrator-set) password, and
+completing missing profile fields.