diff --git a/general/auth.rst b/general/auth.rst index 771c9ea59..e8517445a 100644 --- a/general/auth.rst +++ b/general/auth.rst @@ -9,5 +9,4 @@ Authentication auth/google_spreadsheets auth/azure auth/ldap - - + auth/2fa diff --git a/general/auth/2fa.rst b/general/auth/2fa.rst new file mode 100644 index 000000000..9ebc66d7a --- /dev/null +++ b/general/auth/2fa.rst @@ -0,0 +1,127 @@ +========================= +Two-factor Authentication +========================= + +Two-factor authentication ("2FA") is a good way to improve the +security of an account, to make it less likely that an other person +will manage to log in instead of you. + +Practically, it means storing a secret inside an *authenticator* +(usually your cell phone) and exchanging a code from the authenticator +when you try to log in. + +This means an attacker needs *both* to have guessed (or found) your +password and to access (or steal) your authenticator, a more difficult +proposition than either one or the other. + +Requirements +============ + +.. note:: These lists are just examples, they are not endorsements of + any specific software. + +If you don't already have one, you will need to choose an +authenticator. + +Phone-based authenticators are the easiest and most common so we will +assume you'll pick and install one on your phone, examples include +`Authy `_, `FreeOTP +`_, `Google Authenticator +`_, +`LastPass Authenticator `_, `Microsoft +Authenticator +`_, +...; password managers also commonly include :abbr:`2FA (two-factor +authentication)` support e.g. `1Password +`_, `Bitwarden +`_, ... + +For the sake of demonstration we will be using Google Authenticator +(not because it is any good but because it is quite common). + +Setting up two-factor authentication +==================================== + +Once you have your authenticator of choice, go to the Odoo instance +you want to setup :abbr:`2FA (two-factor authentication)`, then open +:guilabel:`Preferences` (or :guilabel:`My Profile`): + +.. figure:: media/totp_setup/preferences.png + :align: center + +Open the :guilabel:`Account Security` tab, then click the +:guilabel:`Enable two-factor authentication` button: + +.. figure:: media/totp_setup/sec_tab.png + :align: center + +Because this is a security-sensitive action, you will need to input +your password: + +.. figure:: media/totp_setup/sec_enhanced.png + :align: center + +After which you will see this screen with a barcode: + +.. figure:: media/totp_setup/totp_scan.png + :align: center + +In most applications, you can simply *scan the barcode* via the +authenticator of your choice, the authenticator will then take care of +all the setup: + +.. figure:: media/totp_setup/scan_barcode.jpg + :align: center + +.. note:: + + If you can not scan the screen (e.g. because you are doing this + set-up on the same phone as the authenticator application), you can + click the provided link, or copy the secret to manually set-up your + authenticator: + + .. figure:: media/totp_setup/secret_visible.png + :align: center + + .. figure:: media/totp_setup/input_secret.png + :align: center + +Once this is done, the authenticator should display a *verification +code* with some useful identifying information (e.g. the domain and +login for which the code is): + +.. figure:: media/totp_setup/authenticator.png + :align: center + +You can now input the code into the :guilabel:`Verification Code` +field, then click the :guilabel:`Enable two-factor authentication` +button. + +Congratulation, your account is now protected by two-factor +authentication! + +.. figure:: media/totp_setup/totp_enabled.png + :align: center + +Logging in +========== + +You should now :guilabel:`Log out` to follow along. + +On the login page, input the username and password of the account for +which you set up :abbr:`2FA (two-factor authentication)`, rather than +immediately enter Odoo you will now get a second log-in screen: + +.. figure:: media/totp_setup/2fa_input.png + :align: center + +Get your authenticator, input the code it provides for the domain and +account, validate, and you're now in. + +And that's it. From now on, unless you disable :abbr:`2FA (two-factor +authentication)` you will have a two-step log-in process rather than +the old one-step process. + +.. danger:: Don't lose your authenticator, if you do, you will need an + *Odoo Administrator* to disable :abbr:`2FA (two-factor + authentication)` on the account. diff --git a/general/auth/media/totp_setup/2fa_input.png b/general/auth/media/totp_setup/2fa_input.png new file mode 100644 index 000000000..dc0942556 Binary files /dev/null and b/general/auth/media/totp_setup/2fa_input.png differ diff --git a/general/auth/media/totp_setup/authenticator.png b/general/auth/media/totp_setup/authenticator.png new file mode 100644 index 000000000..1fa1b5d55 Binary files /dev/null and b/general/auth/media/totp_setup/authenticator.png differ diff --git a/general/auth/media/totp_setup/input_secret.png b/general/auth/media/totp_setup/input_secret.png new file mode 100644 index 000000000..8b2184004 Binary files /dev/null and b/general/auth/media/totp_setup/input_secret.png differ diff --git a/general/auth/media/totp_setup/preferences.png b/general/auth/media/totp_setup/preferences.png new file mode 100644 index 000000000..d2446bfb2 Binary files /dev/null and b/general/auth/media/totp_setup/preferences.png differ diff --git a/general/auth/media/totp_setup/scan_barcode.jpg b/general/auth/media/totp_setup/scan_barcode.jpg new file mode 100644 index 000000000..f6ebd0b85 Binary files /dev/null and b/general/auth/media/totp_setup/scan_barcode.jpg differ diff --git a/general/auth/media/totp_setup/sec_enhanced.png b/general/auth/media/totp_setup/sec_enhanced.png new file mode 100644 index 000000000..e55b582a3 Binary files /dev/null and b/general/auth/media/totp_setup/sec_enhanced.png differ diff --git a/general/auth/media/totp_setup/sec_tab.png b/general/auth/media/totp_setup/sec_tab.png new file mode 100644 index 000000000..0e6f9028e Binary files /dev/null and b/general/auth/media/totp_setup/sec_tab.png differ diff --git a/general/auth/media/totp_setup/secret_visible.png b/general/auth/media/totp_setup/secret_visible.png new file mode 100644 index 000000000..e1b68a180 Binary files /dev/null and b/general/auth/media/totp_setup/secret_visible.png differ diff --git a/general/auth/media/totp_setup/totp_enabled.png b/general/auth/media/totp_setup/totp_enabled.png new file mode 100644 index 000000000..1f107a9ac Binary files /dev/null and b/general/auth/media/totp_setup/totp_enabled.png differ diff --git a/general/auth/media/totp_setup/totp_scan.png b/general/auth/media/totp_setup/totp_scan.png new file mode 100644 index 000000000..6598376b8 Binary files /dev/null and b/general/auth/media/totp_setup/totp_scan.png differ