Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Mention WebAuthn in the docs #14982

Merged
merged 3 commits into from
Mar 19, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 31 additions & 6 deletions docs/getting-started/my-account/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 3 additions & 3 deletions docs/installation-and-operations/configuration/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion docs/security-and-privacy/statement-on-security/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.