documentation/content/applications/general/users/2fa.md

136 lines
4.4 KiB
Markdown
Raw Permalink Normal View History

2025-02-27 18:56:07 +07:00
---
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.