Add latest changes from gitlab-org/gitlab@13-6-stable-eev13.6.0-rc42

1 files changed, 160 insertions, 21 deletions

diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md
index 0e645e1b4a3..dacb6c3a5a7 100644
--- a/doc/user/profile/account/two_factor_authentication.md
+++ b/doc/user/profile/account/two_factor_authentication.md
@@ -8,12 +8,13 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Two-factor authentication
 
 Two-factor authentication (2FA) provides an additional level of security to your
-GitLab account. Once enabled, in addition to supplying your username and
-password to login, you'll be prompted for a code generated by your one time password
-authenticator. For example, a password manager on one of your devices.
+GitLab account. After being enabled, in addition to supplying your username and
+password to sign in, you'll be prompted for a code generated by your one-time
+password authenticator (for example, a password manager on one of your devices).
 
-By enabling 2FA, the only way someone other than you can log into your account
-is to know your username and password *and* have access to your one time password secret.
+By enabling 2FA, the only way someone other than you can sign in to your account
+is to know your username and password _and_ have access to your one-time
+password secret.
 
 ## Overview
 
@@ -21,30 +22,30 @@ TIP: **Tip:**
 When you enable 2FA, don't forget to back up your [recovery codes](#recovery-codes)!
 
 In addition to time-based one time passwords (TOTP), GitLab supports U2F
-(universal 2nd factor) devices as the second factor of authentication. Once
+(universal 2nd factor) and WebAuthn (experimental) devices as the second factor of authentication. Once
 enabled, in addition to supplying your username and password to log in, you'll
-be prompted to activate your U2F device (usually by pressing a button on it),
+be prompted to activate your U2F / WebAuthn device (usually by pressing a button on it),
 and it will perform secure authentication on your behalf.
 
 It is highly recommended that you set up 2FA with both a
-[one-time password authenticator](#enable-2fa-via-one-time-password-authenticator)
-and a [U2F device](#enable-2fa-via-u2f-device), so you can still access your account
-if you lose your U2F device.
+[one-time password authenticator](#one-time-password) or use [FortiAuthenticator](#one-time-password-via-fortiauthenticator)
+and a [U2F device](#u2f-device) or a [WebAuthn device](#webauthn-device), so you can still access your account
+if you lose your U2F / WebAuthn device.
 
 ## Enabling 2FA
 
-There are two ways to enable two-factor authentication: via a one time password authenticator
-or a U2F device.
+There are multiple ways to enable two-factor authentication: via a one time password authenticator
+or a U2F / WebAuthn device.
 
-### Enable 2FA via one time password authenticator
+### One-time password
 
 To enable 2FA:
 
 1. **In GitLab:**
-   1. Log in to your GitLab account.
+   1. Sign in to your GitLab account.
    1. Go to your [**Profile settings**](../index.md#profile-settings).
    1. Go to **Account**.
-   1. Click **Enable Two-factor Authentication**.
+   1. Select **Enable Two-factor Authentication**.
 1. **On your device (usually your phone):**
    1. Install a compatible application, like:
       - [Authenticator](https://mattrubin.me/authenticator/): open source app for iOS devices.
@@ -59,14 +60,88 @@ To enable 2FA:
 1. **In GitLab:**
    1. Enter the six-digit pin number from the entry on your device into the **Pin
       code** field.
-   1. Click **Submit**.
+   1. Select **Submit**.
 
 If the pin you entered was correct, you'll see a message indicating that
 two-factor authentication has been enabled, and you'll be presented with a list
-of [recovery codes](#recovery-codes). Make sure you download them and keep them
+of [recovery codes](#recovery-codes). Be sure to download them and keep them
 in a safe place.
 
-### Enable 2FA via U2F device
+### One-time password via FortiAuthenticator
+
+> - Introduced in [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/212312)
+> - It's deployed behind a feature flag, disabled by default.
+> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-fortiauthenticator-integration).
+
+You can use FortiAuthenticator as an OTP provider in GitLab. Users must exist in
+both FortiAuthenticator and GitLab with the exact same username, and users must
+have FortiToken configured in FortiAuthenticator.
+
+You'll also need a username and access token for FortiAuthenticator. The
+`access_token` in the code samples shown below is the FortAuthenticator access
+key. To get the token, see the `REST API Solution Guide` at
+[`Fortinet Document Library`](https://docs.fortinet.com/document/fortiauthenticator/6.2.0/rest-api-solution-guide/158294/the-fortiauthenticator-api).
+GitLab 13.5 has been tested with FortAuthenticator version 6.2.0.
+
+First configure FortiAuthenticator in GitLab. On your GitLab server:
+
+1. Open the configuration file.
+
+   For Omnibus GitLab:
+
+   ```shell
+   sudo editor /etc/gitlab/gitlab.rb
+   ```
+
+   For installations from source:
+
+   ```shell
+   cd /home/git/gitlab
+   sudo -u git -H editor config/gitlab.yml
+   ```
+
+1. Add the provider configuration:
+
+   For Omnibus package:
+
+   ```ruby
+   gitlab_rails['forti_authenticator_enabled'] = true
+   gitlab_rails['forti_authenticator_host'] = 'forti_authenticator.example.com'
+   gitlab_rails['forti_authenticator_port'] = 443
+   gitlab_rails['forti_authenticator_username'] = '<some_username>'
+   gitlab_rails['forti_authenticator_access_token'] = 's3cr3t'
+   ```
+
+   For installations from source:
+
+   ```yaml
+   forti_authenticator:
+     enabled: true
+     host: forti_authenticator.example.com
+     port: 443
+     username: <some_username>
+     access_token: s3cr3t
+   ```
+
+1. Save the configuration file.
+1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure)
+   or [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source)
+   for the changes to take effect if you installed GitLab via Omnibus or from
+   source respectively.
+
+#### Enable FortiAuthenticator integration
+
+This feature comes with the `:forti_authenticator` feature flag disabled by
+default.
+
+To enable this feature, ask a GitLab administrator with [Rails console access](../../../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags)
+to run the following command:
+
+```ruby
+Feature.enable(:forti_authenticator, User.find(<user ID>))
+```
+
+### U2F device
 
 > Introduced in [GitLab 8.9](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/).
 
@@ -100,10 +175,46 @@ To set up 2FA with a U2F device:
 You will see a message indicating that your device was successfully set up.
 Click on **Register U2F Device** to complete the process.
 
+### WebAuthn device
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4.
+> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default.
+> - It's disabled on GitLab.com.
+> - It's not recommended for production use.
+> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-webauthn). **(CORE ONLY)**
+
+The WebAuthn workflow is [supported by](https://caniuse.com/#search=webauthn) the
+following desktop browsers:
+
+- Chrome
+- Edge
+- Firefox
+- Opera
+- Safari
+
+and the following mobile browsers:
+
+- Chrome for Android
+- Firefox for Android
+- iOS Safari (since iOS 13.3)
+
+To set up 2FA with a WebAuthn compatible device:
+
+1. Sign in to your GitLab account.
+1. Go to your [**Profile settings**](../index.md#profile-settings).
+1. Go to **Account**.
+1. Select **Enable Two-Factor Authentication**.
+1. Plug in your WebAuthn device.
+1. Select **Set up New WebAuthn Device**.
+1. Depending on your device, you might need to press a button or touch a sensor.
+
+You will see a message indicating that your device was successfully set up.
+Recovery codes are not generated for WebAuthn devices.
+
 ## Recovery codes
 
 NOTE: **Note:**
-Recovery codes are not generated for U2F devices.
+Recovery codes are not generated for U2F / WebAuthn devices.
 
 CAUTION: **Caution:**
 Each code can be used only once to log in to your account.
@@ -141,6 +252,14 @@ To log in via a U2F device:
 You will see a message indicating that your device responded to the authentication
 request and you will be automatically logged in.
 
+### Log in via WebAuthn device
+
+In supported browsers you should be automatically prompted to activate your WebAuthn device
+(e.g. by touching/pressing its button) after entering your credentials.
+
+You will see a message indicating that your device responded to the authentication
+request and you will be automatically logged in.
+
 ## Disabling 2FA
 
 If you ever need to disable 2FA:
@@ -151,7 +270,7 @@ If you ever need to disable 2FA:
 1. Click **Disable**, under **Two-Factor Authentication**.
 
 This will clear all your two-factor authentication registrations, including mobile
-applications and U2F devices.
+applications and U2F / WebAuthn devices.
 
 ## Personal access tokens
 
@@ -257,7 +376,8 @@ Sign in and re-enable two-factor authentication as soon as possible.
   you may have cases where authorization always fails because of time differences.
 - The GitLab U2F implementation does _not_ work when the GitLab instance is accessed from
   multiple hostnames, or FQDNs. Each U2F registration is linked to the _current hostname_ at
-  the time of registration, and cannot be used for other hostnames/FQDNs.
+  the time of registration, and cannot be used for other hostnames/FQDNs. The same applies to
+  WebAuthn registrations.
 
   For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`:
 
@@ -268,6 +388,25 @@ Sign in and re-enable two-factor authentication as soon as possible.
 
 - To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md).
 
+## Enable or disable WebAuthn **(CORE ONLY)**
+
+Support for WebAuthn is under development and not ready for production use. It is
+deployed behind a feature flag that is **disabled by default**.
+[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
+can enable it.
+
+To enable it:
+
+```ruby
+Feature.enable(:webauthn)
+```
+
+To disable it:
+
+```ruby
+Feature.disable(:webauthn)
+```
+
 ## Troubleshooting
 
 If you are receiving an `invalid pin code` error, this may indicate that there is a time sync issue between the authentication application and the GitLab instance itself.