diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-19 11:27:35 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-11-19 11:27:35 +0300 |
commit | 7e9c479f7de77702622631cff2628a9c8dcbc627 (patch) | |
tree | c8f718a08e110ad7e1894510980d2155a6549197 /doc/user/profile/account/two_factor_authentication.md | |
parent | e852b0ae16db4052c1c567d9efa4facc81146e88 (diff) |
Add latest changes from gitlab-org/gitlab@13-6-stable-eev13.6.0-rc42
Diffstat (limited to 'doc/user/profile/account/two_factor_authentication.md')
-rw-r--r-- | doc/user/profile/account/two_factor_authentication.md | 181 |
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. |