diff options
Diffstat (limited to 'doc/user/profile/account')
-rw-r--r-- | doc/user/profile/account/create_accounts.md | 4 | ||||
-rw-r--r-- | doc/user/profile/account/delete_account.md | 2 | ||||
-rw-r--r-- | doc/user/profile/account/img/register_tab.png | bin | 69998 -> 0 bytes | |||
-rw-r--r-- | doc/user/profile/account/img/register_v13_6.png | bin | 0 -> 42777 bytes | |||
-rw-r--r-- | doc/user/profile/account/two_factor_authentication.md | 181 |
5 files changed, 163 insertions, 24 deletions
diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index 09bfa7afc9e..cf5e4591a50 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -14,9 +14,9 @@ You can create users: ## Create users on sign in page -If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md), users can create their own accounts using the **Register** tab on the sign in page. +If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md), users can create their own accounts by selecting "Register now" on the sign-in page, or navigate to `https://gitlab.example.com/users/sign_up`. -![Register Tab](img/register_tab.png) +![Register Tab](img/register_v13_6.png) ## Create users in Admin Area diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index a70d11438f4..637d740ab0f 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -35,7 +35,7 @@ As an administrator, you can delete a user account by: - **Delete user and contributions** to delete the user and their associated records. -DANGER: **Danger:** +DANGER: **Warning:** Using the **Delete user and contributions** option may result in removing more data than intended. Please see [associated records](#associated-records) below for additional details. diff --git a/doc/user/profile/account/img/register_tab.png b/doc/user/profile/account/img/register_tab.png Binary files differdeleted file mode 100644 index 4bbb4e62687..00000000000 --- a/doc/user/profile/account/img/register_tab.png +++ /dev/null diff --git a/doc/user/profile/account/img/register_v13_6.png b/doc/user/profile/account/img/register_v13_6.png Binary files differnew file mode 100644 index 00000000000..ce4adc0f55b --- /dev/null +++ b/doc/user/profile/account/img/register_v13_6.png 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. |