Mention WebAuthn in the docs (#14982)

* Mention WebAuthn in the docs * Update 2FA documentation Adding WebAuth option to the user guide Adding mobile option to the user guide Exchanging screenshots to reflect latest primer changes * Fixing a link --------- Co-authored-by: Maya Berdygylyjova <MayaBerd@users.noreply.github.com>
opf · Mar 19, 2024 · e497e30 · e497e30
1 parent 5e7ec11
commit e497e30
Show file tree

Hide file tree

Showing 10 changed files with 43 additions and 12 deletions.
diff --git a/docs/getting-started/my-account/README.md b/docs/getting-started/my-account/README.md
@@ -104,32 +104,57 @@ 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
 
 Register an application authenticator for use with OpenProject using the time-based one-time password authentication standard. Common examples are Google Authenticator or Authy.
 
 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
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
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
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
diff --git a/...getting-started/my-account/openproject_my_account_two_factor_authentication.png b/...getting-started/my-account/openproject_my_account_two_factor_authentication.png
diff --git a/...-started/my-account/openproject_my_account_two_factor_authentication_mobile.png b/...-started/my-account/openproject_my_account_two_factor_authentication_mobile.png
diff --git 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
@@ -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
@@ -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.