136 lines
4.4 KiB
Markdown
136 lines
4.4 KiB
Markdown
|
---
|
||
|
substitutions:
|
||
|
2fa: '{abbr}`2FA (two-factor authentication)`'
|
||
|
QR: '{abbr}`QR (Quick Response)` code'
|
||
|
---
|
||
|
|
||
|
# Two-factor authentication
|
||
|
|
||
|
*Two-factor authentication (2FA)* is a way to improve security, and prevent unauthorized persons
|
||
|
from accessing user accounts.
|
||
|
|
||
|
Practically, {{ 2fa }} means storing a secret inside an *authenticator*, usually on a mobile phone, and
|
||
|
exchanging a code from the authenticator when trying to log in.
|
||
|
|
||
|
This means an unauthorized user would need to guess the account password *and* have access to the
|
||
|
authenticator, which is a more difficult proposition.
|
||
|
|
||
|
## Requirements
|
||
|
|
||
|
:::{important}
|
||
|
These lists are just examples. They are **not** endorsements of any specific software.
|
||
|
:::
|
||
|
|
||
|
Phone-based authenticators are the easiest and most commonly used. Examples include:
|
||
|
|
||
|
- [Authy](https://authy.com/)
|
||
|
- [FreeOTP](https://freeotp.github.io/)
|
||
|
- [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en)
|
||
|
- [LastPass Authenticator](https://lastpass.com/auth/)
|
||
|
- [Microsoft Authenticator](https://www.microsoft.com/en-gb/account/authenticator?cmp=h66ftb_42hbak)
|
||
|
|
||
|
Password managers are another option. Common examples include:
|
||
|
|
||
|
- [1Password](https://support.1password.com/one-time-passwords/)
|
||
|
- [Bitwarden](https://bitwarden.com/help/article/authenticator-keys/),
|
||
|
|
||
|
:::{note}
|
||
|
The remainder of this document uses Google Authenticator as an example, as it is one of the most
|
||
|
commonly used. This is **not** an endorsement of the product.
|
||
|
:::
|
||
|
|
||
|
## Two-factor authentication setup
|
||
|
|
||
|
After selecting an authenticator, log in to Odoo, then click the profile avatar in the upper-right
|
||
|
corner, and select {guilabel}`My Profile` from the resulting drop-down menu.
|
||
|
|
||
|
Click the {guilabel}`Account Security` tab, then slide the {guilabel}`Two-Factor Authentication`
|
||
|
toggle to *active*.
|
||
|
|
||
|
:::{figure} 2fa/account-security.png
|
||
|
:align: center
|
||
|
:::
|
||
|
|
||
|
This generates a {guilabel}`Security Control` pop-up window that requires password confirmation to
|
||
|
continue. Enter the appropriate password, then click {guilabel}`Confirm Password`. Next, a
|
||
|
{guilabel}`Two-Factor Authentication Activation` pop-up window appears, with a {{ QR }}.
|
||
|
|
||
|
:::{figure} 2fa/qr-code.png
|
||
|
:align: center
|
||
|
:::
|
||
|
|
||
|
Using the desired authenticator application, scan the {{ QR }} when prompted.
|
||
|
|
||
|
::::{tip}
|
||
|
If scanning the screen is not possible (e.g. the setup is being completed on the *same* device as
|
||
|
the authenticator application), clicking the provided {guilabel}`Cannot scan it?` link, or
|
||
|
copying the secret to manually set up the authenticator, is an alternative.
|
||
|
|
||
|
:::{figure} 2fa/secret-visible.png
|
||
|
:align: center
|
||
|
:::
|
||
|
|
||
|
:::{figure} 2fa/input-secret.png
|
||
|
:align: center
|
||
|
:::
|
||
|
::::
|
||
|
|
||
|
Afterwards, the authenticator should display a *verification code*.
|
||
|
|
||
|
:::{figure} 2fa/authenticator.png
|
||
|
:align: center
|
||
|
:::
|
||
|
|
||
|
Enter the code into the {guilabel}`Verification Code` field, then click {guilabel}`Activate`.
|
||
|
|
||
|
:::{figure} 2fa/2fa-enabled.png
|
||
|
:align: center
|
||
|
:::
|
||
|
|
||
|
## Logging in
|
||
|
|
||
|
To confirm {{ 2fa }} setup is complete, log out of Odoo.
|
||
|
|
||
|
On the login page, input the username and password, then click {guilabel}`Log in`. On the
|
||
|
{guilabel}`Two-factor Authentication` page, input the code provided by the chosen authenticator in
|
||
|
the {guilabel}`Authentication Code` field, then click {guilabel}`Log in`.
|
||
|
|
||
|
```{image} 2fa/2fa-login.png
|
||
|
:align: center
|
||
|
:alt: The login page with 2fa enabled.
|
||
|
```
|
||
|
|
||
|
:::{danger}
|
||
|
If a user loses access to their authenticator, an administrator **must** deactivate {{ 2fa }} on the
|
||
|
account before the user can log in.
|
||
|
:::
|
||
|
|
||
|
## Enforce two-factor authentication
|
||
|
|
||
|
To enforce the use of {{ 2fa }} for all users, first navigate to {menuselection}`Main Odoo Dashboard -->
|
||
|
Apps`. Remove the {guilabel}`Apps` filter from the {guilabel}`Search...` bar, then search for `2FA
|
||
|
by mail`.
|
||
|
|
||
|
Click {guilabel}`Install` on the Kanban card for the {guilabel}`2FA by mail` module.
|
||
|
|
||
|
```{image} 2fa/2FA-by-mail.png
|
||
|
:align: center
|
||
|
:alt: The 2FA by mail module in the Apps directory.
|
||
|
```
|
||
|
|
||
|
After installation is complete, go to {guilabel}`Settings app: Permissions`. Tick the checkbox
|
||
|
labeled, {guilabel}`Enforce two-factor authentication`. Then, use the radio buttons to choose
|
||
|
whether to apply this setting to {guilabel}`Employees only`, or {guilabel}`All users`.
|
||
|
|
||
|
:::{note}
|
||
|
Selecting {guilabel}`All users` applies the setting to portal users, in addition to employees.
|
||
|
:::
|
||
|
|
||
|
```{image} 2fa/enforce-settings.png
|
||
|
:align: center
|
||
|
:alt: The enforce two factor setting in the Settings application.
|
||
|
```
|
||
|
|
||
|
Click {guilabel}`Save` to commit any unsaved changes.
|
||
|
|