diff --git a/docs/getting-started/my-account/README.md b/docs/getting-started/my-account/README.md index 6a90e94c7868..a47a2ae730cf 100644 --- a/docs/getting-started/my-account/README.md +++ b/docs/getting-started/my-account/README.md @@ -104,21 +104,32 @@ Press the blue **Save** button in order to confirm the password changes. ## Two-factor authentication -In order to activate the two-factor authentication for your OpenProject installation, navigate to your **My account** and choose the **Two-factor authentication** in the menu. +In order to activate the two-factor authentication for your OpenProject installation, navigate to your **My account** and choose the **Two-factor authentication** in the menu. If you have not added any device yet, this list will be empty. ![OpenProject my account two_factor authentication](openproject_my_account_two_factor_authentication.png) -In order to register a new device for two-factor authentication, click the green button to add a **new 2FA device**. +If you have already registered one or multiple 2FA devices, you will see the list of all activated 2FA devices here. You can change, which of them you prefer to have set a a default option. + +![List of all registered 2FA devices in OpenProject](openproject_my_account_2fa_overview.png) + +In order to register a new device for two-factor authentication, click the green button to add a **new 2FA device**. You will see the screen, where you will be able to see one or multiple of the following options, depending on what your system administrator has [activated for your instance](../../system-admin-guide/authentication/two-factor-authentication/): + +- Mobile phone +- App-based authenticator +- WebAuth + +![](openproject_my_account_authentication_options.png) To receive the second factor, you can use an authentication app on your mobile phone, such as Google Authenticator or Authy. You have to enter the code that is displayed in the authentication app to your login. You can remove or approve 2FA applications by confirming your password. Note that this applies only to internally authenticated users. -### Backup codes +### Use your mobile phone -If you are unable to access your two-factor devices, you can use a backup code to regain access to your account. Use the grey button **Generate backup codes** to generate a new set of backup codes. +You can use your mobile phone as a 2FA device. The field *Identifier* will be pre-filled out, you will need to add your phone number and click the green **Continue** button. + +![Add a new mobile phone as a 2FA device in OpenProject](openproject_my_account_two_factor_authentication_mobile.png) -If you have created backup codes before, they will be invalidated and will no longer work. ### Use your app-based authenticator @@ -126,10 +137,24 @@ Register an application authenticator for use with OpenProject using the time-ba Click the grey **Register device** button to register an authentication app. Open your app and follow the instructions to add a new application. The easiest way is to scan the QR code. Otherwise, you can register the application manually by entering the displayed details. -Click the blue **Continue** button to finish the registration. +Click the green **Continue** button to finish the registration. ![openproject_my_account_authenticator_app](openproject_my_account_authenticator_app.png) +### Use the WebAuth authentication + +Use Web Authentication to register a FIDO2 device (like a YubiKey) or the secure enclave of your mobile device as a second factor. After you have chosen a name, you can click the green **Continue** button. + +![](openproject_my_account_authenticator_webauth.png) + +Your browser will prompt you to present your WebAuthn device (depending on your operational system and your browser, your options may vary). When you have done so, you are done registering the device. + +### Backup codes + +If you are unable to access your two-factor devices, you can use a backup code to regain access to your account. Use the grey button **Generate backup codes** to generate a new set of backup codes. + +If you have created backup codes before, they will be invalidated and will no longer work. + ## Access tokens To view and manage your OpenProject access tokens navigate to **My account** and choose **Access tokens** from the menu. Access tokens allow you to grant external applications access to resources in OpenProject. diff --git a/docs/getting-started/my-account/openproject_my_account_2fa_overview.png b/docs/getting-started/my-account/openproject_my_account_2fa_overview.png new file mode 100644 index 000000000000..161ca2b95701 Binary files /dev/null and b/docs/getting-started/my-account/openproject_my_account_2fa_overview.png differ diff --git a/docs/getting-started/my-account/openproject_my_account_authentication_options.png b/docs/getting-started/my-account/openproject_my_account_authentication_options.png new file mode 100644 index 000000000000..465a6eaf7303 Binary files /dev/null and b/docs/getting-started/my-account/openproject_my_account_authentication_options.png differ diff --git a/docs/getting-started/my-account/openproject_my_account_authenticator_app.png b/docs/getting-started/my-account/openproject_my_account_authenticator_app.png index 7cf7956ae9c7..f3cf1a9474d2 100644 Binary files a/docs/getting-started/my-account/openproject_my_account_authenticator_app.png and b/docs/getting-started/my-account/openproject_my_account_authenticator_app.png differ diff --git a/docs/getting-started/my-account/openproject_my_account_authenticator_webauth.png b/docs/getting-started/my-account/openproject_my_account_authenticator_webauth.png new file mode 100644 index 000000000000..e02686fb1c9c Binary files /dev/null and b/docs/getting-started/my-account/openproject_my_account_authenticator_webauth.png differ diff --git a/docs/getting-started/my-account/openproject_my_account_two_factor_authentication.png b/docs/getting-started/my-account/openproject_my_account_two_factor_authentication.png index 537f82ea278a..5a3c82644068 100644 Binary files a/docs/getting-started/my-account/openproject_my_account_two_factor_authentication.png and b/docs/getting-started/my-account/openproject_my_account_two_factor_authentication.png differ diff --git a/docs/getting-started/my-account/openproject_my_account_two_factor_authentication_mobile.png b/docs/getting-started/my-account/openproject_my_account_two_factor_authentication_mobile.png new file mode 100644 index 000000000000..2ccc05254f5c Binary files /dev/null and b/docs/getting-started/my-account/openproject_my_account_two_factor_authentication_mobile.png differ diff --git a/docs/installation-and-operations/configuration/README.md b/docs/installation-and-operations/configuration/README.md index dcfe7449f45e..92e9234ecf47 100644 --- a/docs/installation-and-operations/configuration/README.md +++ b/docs/installation-and-operations/configuration/README.md @@ -424,7 +424,7 @@ OPENPROJECT_OVERRIDE__BCRYPT__COST__FACTOR="16" ## Database configuration and SSL -Please see [this separate guide](./database/) on how to set a custom database connection string and optionally, require SSL/TTLS verification. +Please see [this separate guide](./database/) on how to set a custom database connection string and optionally, require SSL/TTLS verification. ## disable password login @@ -589,7 +589,7 @@ You can optionally enable additional rules on API rate limiting as follows: `OPENPROJECT_RATE_LIMITING_API__V3=true` -Additional application-level rate limiting rules will be added in the future. Additionally to these application level rules, use your load balancer / proxying web server to apply individual rate limiting rules using modules such as `ngx_http_limit_req_module` or `mod_security`. +Additional application-level rate limiting rules will be added in the future. Additionally to these application level rules, use your load balancer / proxying web server to apply individual rate limiting rules using modules such as `ngx_http_limit_req_module` or `mod_security`. ### Blacklisted routes @@ -758,7 +758,7 @@ OPENPROJECT_2FA_ENFORCED="true" **Setting available strategies** -By default, the TOTP strategy for phone authenticator apps is active. +By default, the TOTP and WebAuthn strategie are active. If you have a [MessageBird account](https://www.messagebird.com/), you can setup a SMS 2FA by activating that strategy like so: diff --git a/docs/security-and-privacy/statement-on-security/README.md b/docs/security-and-privacy/statement-on-security/README.md index 08736dbe7b75..6d4800b67b30 100644 --- a/docs/security-and-privacy/statement-on-security/README.md +++ b/docs/security-and-privacy/statement-on-security/README.md @@ -80,7 +80,7 @@ Admins can set a specific session duration in the system administration, so that ### Two-factor authentication -Secure your authentication mechanisms with a second factor by TOTP standard (or SMS, depending on your instance) to be entered by users upon logging in. +Secure your authentication mechanisms with a second factor by TOTP and WebAuthn standards (or SMS, depending on your instance) to be provided by users upon logging in. ### Security badge diff --git a/docs/system-admin-guide/authentication/two-factor-authentication/README.md b/docs/system-admin-guide/authentication/two-factor-authentication/README.md index d4ad60003c3c..59b4ff87da1e 100644 --- a/docs/system-admin-guide/authentication/two-factor-authentication/README.md +++ b/docs/system-admin-guide/authentication/two-factor-authentication/README.md @@ -36,8 +36,14 @@ By default, the allowed clock skew (difference in seconds between client and ser If you are trying to register a new device and keep getting failures even though the code appears correct, time drift between the device and the server is most likely the reason for it. +## Basic 2FA using WebAuthn + +[WebAuthn](https://www.w3.org/TR/2019/REC-webauthn-1-20190304/) is a W3C standard for authentication on the web. It uses private-public key cryptography to verify the users identity. The private key is either secured on a hardware token or within the browser or a password manager. + +WebAuthn is supported by most modern browsers and is therefore enabled by default in OpenProject when 2FA is enabled. + ## Advanced 2FA using MessageBird, Amazon SNS -At the moment the advanced settings for improved security are only reachable on the by defining [configuration variables](../../../installation-and-operations/configuration/). +At the moment the advanced settings for improved security are only reachable by defining [configuration variables](../../../installation-and-operations/configuration/). -The how to is explained in the configuration is explained in the [Two-factor authentication](../../../installation-and-operations/configuration/#two-factor-authentication) paragraph. +Those methods are explained in the [Two-factor authentication](../../../installation-and-operations/configuration/#two-factor-authentication) paragraph.