Document two-factor authentication

source/faq/index.rst

@@ -20,6 +20,71 @@ Galette logs are stored in the ``galette/data/log`` per default.
 
 :ref:`Enabling development mode <galettemodes>` will give you more information, and deactivate cache, that may help resolving your issue.
 
+.. _faq_2fa:
+
+************************************************
+My two-factor authentication codes are refused
+************************************************
+
+.. versionadded:: 1.3.0
+
+**Check the clocks first.** Codes are computed from the current time, and nothing else. If the clock of your server or the clock of your device is off by more than about a minute, every code is refused, and everything else looks perfectly normal. This is, by a wide margin, the first thing to look at.
+
+Galette accepts the code of the current thirty seconds period and of the one just before and just after, which leaves a bit less than a minute and a half of tolerance. Beyond that, set both clocks right -- on the server, by enabling NTP; on a phone, by turning automatic date and time on -- and try again. Most authenticator applications also offer to correct their own clock for you.
+
+Two other cases look like a refusal but are not one:
+
+* **the same code twice**: a code is accepted once only, so submitting the code you just used to enrol, or reloading the page after a successful login, is refused. Wait for the next one -- it comes at most thirty seconds later.
+* **too many attempts**: after a series of wrong codes, Galette stops answering for a while. Wait it out rather than trying harder.
+
+The server clock went backwards
+-------------------------------
+
+Galette remembers the last period it accepted a code for, so that a code cannot be used twice. If the clock of the **server** moves backwards -- a virtual machine restored from a snapshot, a large NTP correction, a host without NTP at all -- every code then falls in a period that has already been used, and is refused as such until the clock catches up with what was recorded.
+
+Set the server clock right first. Then, for the account concerned:
+
+.. code-block:: sql
+
+   UPDATE galette_twofactor SET last_timeslice = NULL WHERE id_adh = <member id>;
+
+and, for the super administrator:
+
+.. code-block:: sql
+
+   UPDATE galette_preferences SET val_pref = '0' WHERE nom_pref = 'pref_2fa_superadmin_timeslice';
+
+I lost the device computing my codes
+------------------------------------
+
+Use one of the ten recovery codes you were given when you enabled it: the field that asks for a code takes them too. Each one works once. Once logged in, disable the second factor and enable it again on your new device -- and keep the new recovery codes.
+
+If you have no recovery code left either, ask an administrator or a staff member of your association to :ref:`reset your second factor <member_2fa_reset>`.
+
+The super administrator cannot log in anymore
+---------------------------------------------
+
+That account is not a member, so nobody can reset it from the interface, and it has no recovery codes. Its second factor lives in the preferences, in database, which is where you clear it from:
+
+.. code-block:: sql
+
+   UPDATE galette_preferences SET val_pref = '' WHERE nom_pref = 'pref_2fa_superadmin_secret';
+   UPDATE galette_preferences SET val_pref = '0' WHERE nom_pref = 'pref_2fa_superadmin_enabled';
+
+Replace ``galette_`` with your own table prefix if you changed it (the ``PREFIX_DB`` setting of your configuration file). The next login asks for the password alone.
+
+To turn the second factor off for the whole instance at the same time -- the way out when something goes wrong for everybody at once -- add:
+
+.. code-block:: sql
+
+   UPDATE galette_preferences SET val_pref = '0' WHERE nom_pref = 'pref_2fa_mode';
+
+Members who had enabled one keep it; they are simply no longer asked for a code until a policy is set again.
+
+.. warning::
+
+   Keep an access to your database at hand before you enable a second factor on the super administrator account. It is the only way back in for it.
+
 *****************************************
 How to report a bug or ask for a feature?
 *****************************************

source/installation/postinstall.rst

@@ -51,3 +51,13 @@ You and your members will login to Galette, using a login and a password. You mu
 This problem is recurrent hen you have to send data over the internet, and this is why you must check if you are on a HTTPS secured page (your browser will tell you), when you enter any sensitive information such as login, passwords, credit card number, ...
 
 And this is the same for Galette, you can use it along with SSL, no problem. All data that will be transmitted to the server will be a bit more confident and secured :)
+
+Since Galette 1.3.0, you can also ask for :ref:`a second factor at login <pref_2fa>`, so that a password that leaked is not enough on its own.
+
+.. note::
+
+   Codes are computed from the current time: make sure your server clock is right, and kept right (NTP). A server drifting away refuses every code, without saying why.
+
+   Before enabling a second factor on the super administrator account, check you can reach your database. That account has no recovery codes, and :ref:`clearing its second factor <faq_2fa>` is done there.
+
+   Which also means: a second factor protects the login form, not the server. Whoever can write in your database or in your configuration file can turn it off. Keep both out of reach.

source/usermanual/adherents.rst

@@ -265,6 +265,21 @@ The other interesting point of this system is you can retrieve some information
 
 .. note:: Members without email adresses cannot use the "retrieve password" feature. This does not affect the uniqueness email constraint in the database.
 
+.. _member_2fa_reset:
+
+Resetting a second factor
+=========================
+
+.. versionadded:: 1.3.0
+
+A member who lost the device computing their codes, and has no :ref:`recovery code <man_2fa>` left either, cannot log in anymore. From the member page, administrators and staff members can reset their second factor: the secret and the remaining recovery codes are dropped, and the member logs in with their password alone until they enrol again.
+
+A reset only ever goes downwards. Your own second factor is not reset from here -- use your own page, which asks for a code first, so that a session somebody else found open cannot remove it. A staff member cannot reset an administrator's, and an administrator cannot reset another administrator's: only the super administrator can.
+
+.. warning::
+
+   Do check who is asking. Resetting a second factor removes a protection, and a phone call claiming to be a member is exactly how somebody would go about getting one removed. The reset is recorded in the history, with who did it and for whom.
+
 Impersonating
 =============
 

source/usermanual/generalites.rst

@@ -55,6 +55,58 @@ He is not an up to date member from 2006-01-01 to 2006-01-13... On paper at leas
 
 Those rules are flexible because you can freely change membership dates on contributions, if you have rights to add or update them. We can imagine an association who stores all contributions on the first day of the next month (offering its members a longer membership time).
 
+.. _man_2fa:
+
+Two-factor authentication
+=========================
+
+.. versionadded:: 1.3.0
+
+   Marked **experimental**: it is complete and tested, but it is new, and the interface may still change.
+
+Once :ref:`a policy has been set in the preferences <pref_2fa>`, every account can protect itself with a second factor: after the password, Galette asks for a six digits code that changes every thirty seconds.
+
+If you are an administrator or a staff member and have not set one up, Galette invites you to when you log in. Nothing forces you to; **Later** keeps quiet for six months, **Do not ask again** for a year.
+
+You need an application to compute those codes. Any of them will do, they all follow the same standard; among the free ones:
+
+* `Aegis <https://getaegis.app>`_ or `FreeOTP <https://freeotp.github.io>`_ on Android,
+* `KeePassXC <https://keepassxc.org>`_ on a computer, in the *TOTP* field of an entry,
+* Google Authenticator, Microsoft Authenticator, ... on Android and iOS.
+
+Enabling it
+^^^^^^^^^^^
+
+Go to **My account**, then **Two-factor authentication**, and click on *Enable two-factor authentication*. Galette shows a QR code to scan with your application; if you cannot scan it, the key displayed right under it can be typed in by hand instead.
+
+Your application then starts displaying codes. Type the current one in to confirm, and it is on. That first code is asked for on purpose: it makes sure your application really is set up before Galette starts requiring it.
+
+Galette then displays **ten recovery codes**, and displays them only once.
+
+.. warning::
+
+   Print those recovery codes, or save them somewhere that is not the device computing your codes. They are the way back in if you lose your phone. Each one works once, and Galette never shows them again -- it does not keep them in a readable form.
+
+You can get ten new ones at any time from the same page; the previous ones are then void.
+
+Logging in
+^^^^^^^^^^
+
+Nothing changes for the password. Once it has been accepted, Galette asks for a code. Nothing else is reachable until it is given: an account waiting for its code is not logged in.
+
+If you no longer have your device, use one of your recovery codes instead of a code: the same field takes both.
+
+Disabling it
+^^^^^^^^^^^^
+
+From **My account**, then **Two-factor authentication**, a current code is required to turn it off. That is deliberate: somebody who found your session open should not be able to remove your second factor with a click.
+
+If a policy makes it mandatory, you will be asked to enable it again at your next login.
+
+.. note::
+
+   Codes are computed from the current time, so both your device and the server have to agree on it. This is by far the most common reason for codes being refused; see :ref:`the FAQ <faq_2fa>`.
+
 Interface
 =========
 

source/usermanual/preferences.rst

@@ -308,6 +308,36 @@ This check rely on strength activation (all but **none** level). For the super-a
 
 Basically, user cannot use verbatim any of those information as password. Some possible combinations are also checked, like surname and name couple (or name and surname), first letter of surname with name, etc. Birthdate will be checked in different formats as well (localized, international, and some variants).
 
+.. _pref_2fa:
+
+Two-factor authentication
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.3.0
+
+   Marked **experimental**: it is complete and tested, but it is new, and the interface may still change. It is disabled by default; nothing happens until you choose otherwise.
+
+A password is a single factor: whoever knows it is in. Two-factor authentication asks, right after the password, for a six digits code that changes every thirty seconds and comes from an application on the user own phone or computer. A stolen password is then not enough anymore.
+
+Galette implements the TOTP standard (:rfc:`6238`), the one every authenticator application speaks; no third party service is involved, and nothing leaves your server.
+
+Two policies are available:
+
+* **disabled** (default): nothing changes, nobody is asked for a code,
+* **optional**: everybody may enable it from their own account, nobody has to.
+
+Making the second factor **compulsory** — for administrators and staff members, or for everyone — is written and tested, but it is not offered yet: under a compulsory policy, a server clock that drifts or an enrolment that goes wrong puts a whole association outside its own instance, and the only way back is a command in the database. It is planned for a later version, once the optional policy has been used in the field.
+
+Since nobody is forced to enrol, administrators and staff members — the accounts that can read the civil status, the addresses and the financial data of every member — are invited to set a second factor up when they log in, with a **Later** and a **Do not ask again** button. Declining is remembered in a cookie of the browser, so the invitation comes back on a new browser, or after a year.
+
+.. note::
+
+   Switching the policy back to **disabled** does not delete anything. Codes are no longer asked for, and the second factors already enabled start being asked for again as soon as you enable a policy back. While the policy is disabled, the pages to enable a second factor answer nothing: a factor enrolled then would never be asked for.
+
+The super administrator is covered as well, as any other account. As it is not a member, it has no recovery codes; see :ref:`what to do should you lose it <faq_2fa>`.
+
+Members enable and manage their own second factor from their account; this is described in :ref:`the members part of this manual <man_2fa>`. Administrators and staff members can :ref:`reset the second factor of a member <member_2fa_reset>` who lost it.
+
 Admin
 =====