diff options
Diffstat (limited to 'doc/user/profile/account/two_factor_authentication.md')
| -rw-r--r-- | doc/user/profile/account/two_factor_authentication.md | 225 |
1 files changed, 140 insertions, 85 deletions
diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index b76b99b5242..8827e1e27c5 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -14,7 +14,7 @@ GitLab supports as a second factor of authentication: - Time-based one-time passwords ([TOTP](https://datatracker.ietf.org/doc/html/rfc6238)). When enabled, GitLab prompts you for a code when you sign in. Codes are generated by your one-time password authenticator (for example, a password manager on one of your devices). -- U2F or WebAuthn devices. You're prompted to activate your U2F or WebAuthn device (usually by pressing a button on it) when +- WebAuthn devices. You're prompted to activate your WebAuthn device (usually by pressing a button on it) when you supply your username and password to sign in. This performs secure authentication on your behalf. If you set up a device, also set up a TOTP so you can still access your account if you lose the device. @@ -24,28 +24,37 @@ If you set up a device, also set up a TOTP so you can still access your account When 2FA is enabled, you can't use your password to authenticate with Git over HTTPS or the [GitLab API](../../../api/rest/index.md). You can use a [personal access token](../personal_access_tokens.md) instead. -## Git Credential Manager +## OAuth credential helpers -For Git over HTTPS, [Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) offers an alternative to personal access tokens. By default, GCM -authenticates using OAuth, opening GitLab in your web browser. The first time you authenticate, GitLab asks you to authorize the app. If you remain signed in to GitLab, subsequent -authentication requires no interaction. +The following Git credential helpers authenticate to GitLab using OAuth. This is compatible with two-factor authentication. The first time you authenticate, the helper opens the web browser and GitLab asks you to authorize the app. Subsequent authentication requires no interaction. -So you don't need to reauthenticate on every push, GCM supports caching as well as a variety of platform-specific credential stores that persist between sessions. This feature is useful whether you use personal access tokens or OAuth. +### Git Credential Manager -GCM supports GitLab.com out the box. To use with self-managed GitLab, see [GitLab support](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/gitlab.md) -documentation. +[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) authenticates by default using OAuth. GCM supports GitLab.com without any manual configuration. To use GCM with self-managed GitLab, see [GitLab support](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/gitlab.md). + +So you do not need to re-authenticate on every push, GCM supports caching as well as a variety of platform-specific credential stores that persist between sessions. This feature is useful whether you use personal access tokens or OAuth. + +Git for Windows includes Git Credential Manager. Git Credential Manager is developed primarily by GitHub, Inc. It is an open-source project and is supported by the community. +### git-credential-oauth + +[git-credential-oauth](https://github.com/hickford/git-credential-oauth) supports GitLab.com and several popular public hosts without any manual configuration needed. To use with self-managed GitLab, see the [git-credential-oauth custom hosts documentation](https://github.com/hickford/git-credential-oauth#custom-hosts). + +Many Linux distributions include git-credential-oauth as a package. + +git-credential-oauth is an open-source project supported by the community. + ## Enable two-factor authentication > - Account email confirmation requirement [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35102) in GitLab 14.3. [Deployed behind the `ensure_verified_primary_email_for_2fa` flag](../../../administration/feature_flags.md), enabled by default. > - Account email confirmation requirement generally available and [feature flag `ensure_verified_primary_email_for_2fa` removed](https://gitlab.com/gitlab-org/gitlab/-/issues/340151) in GitLab 14.4. -You can enable 2FA: +You can enable 2FA using a: -- Using a one-time password authenticator. After you enable 2FA, back up your [recovery codes](#recovery-codes). -- Using a U2F or WebAuthn device. +- One-time password authenticator. After you enable 2FA, back up your [recovery codes](#recovery-codes). +- WebAuthn device. In GitLab 14.3 and later, your account email must be confirmed to enable 2FA. @@ -60,10 +69,11 @@ To enable 2FA with a one-time password: 1. **On your device (usually your phone):** 1. Install a compatible application. For example: - Cloud-based (recommended because you can restore access if you lose the hardware device): - - [Authy](https://authy.com/) + - [Authy](https://authy.com/). + - [Duo](https://duo.com/). - Other: - - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en) - - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app) + - [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en). + - [Microsoft Authenticator](https://www.microsoft.com/en-us/security/mobile-authenticator-app). 1. In the application, add a new entry in one of two ways: - Scan the code displayed by GitLab with your device's camera to add the entry automatically. - Enter the details provided to add the entry manually. @@ -72,9 +82,6 @@ To enable 2FA with a one-time password: 1. Enter your current password. 1. Select **Submit**. -NOTE: -DUO [cannot be used for 2FA](https://gitlab.com/gitlab-org/gitlab/-/issues/15760). - If you entered the correct pin, GitLab displays a list of [recovery codes](#recovery-codes). Download them and keep them in a safe place. @@ -141,6 +148,70 @@ Configure FortiAuthenticator in GitLab. On your GitLab server: 1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or [restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source). +### Enable one-time password using Duo + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15760) in GitLab 15.10. + +FLAG: +On self-managed GitLab, by default this feature is available. On GitLab.com this feature is not available. + +You can use Duo as an OTP provider in GitLab. + +#### Prerequisites + +To use Duo as an OTP provider: + +- Your account must exist in both Duo and GitLab, with the same username in both applications. +- You must have [configured Duo](https://admin.duosecurity.com/) and have an integration key, secret key, and API hostname. + +For more information, see the [Duo API documentation](https://duo.com/docs/authapi). + +GitLab 15.10 has been tested with Duo version D261.14 + +#### Configure Duo 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['duo_auth_enabled'] = false + gitlab_rails['duo_auth_integration_key'] = '<duo_integration_key_value>' + gitlab_rails['duo_auth_secret_key'] = '<duo_secret_key_value>' + gitlab_rails['duo_auth_hostname'] = '<duo_api_hostname>' + ``` + + For installations from source: + + ```yaml + duo_auth: + enabled: true + hostname: <duo_api_hostname> + integration_key: <duo_integration_key_value> + secret_key: <duo_secret_key_value> + ``` + +1. Save the configuration file. +1. For Omnibus GitLab, [reconfigure GitLab](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure). + For installations from source, [restart GitLab](../../../administration/restart_gitlab.md#installations-from-source). + ### Enable one-time password using FortiToken Cloud > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212313) in GitLab 13.7 [with a flag](../../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default. @@ -198,68 +269,61 @@ Configure FortiToken Cloud in GitLab. On your GitLab server: 1. [Reconfigure](../../../administration/restart_gitlab.md#omnibus-gitlab-reconfigure) (Omnibus GitLab) or [restart](../../../administration/restart_gitlab.md#installations-from-source) (GitLab installed from source). -### Set up a U2F device - -GitLab officially supports [YubiKey](https://www.yubico.com/products/) U2F devices, but users have successfully used -[SoloKeys](https://solokeys.com/) and [Google Titan Security Key](https://cloud.google.com/titan-security-key). - -U2F is [supported by](https://caniuse.com/#search=U2F) the following desktop browsers: - -- Chrome -- Edge -- Opera -- Firefox 67+. For Firefox 47-66: - - 1. Enable the FIDO U2F API in [`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox). - 1. Search for `security.webauth.u2f` and select it to toggle to `true`. - -To set up 2FA with a U2F device: - -1. Access your [**User settings**](../index.md#access-your-user-settings). -1. Select **Account**. -1. Select **Enable Two-Factor Authentication**. -1. Connect your U2F device. -1. Select **Set up New U2F Device**. -1. A light begins blinking on your device. Activate it by pressing its button. - -A message displays indicating that your device was successfully set up. Select **Register U2F Device** to complete the -process. Recovery codes are not generated for U2F devices. - ### Set up a WebAuthn device -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `webauthn`. Disabled by default. -> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/232671) in GitLab 14.6. +> - WebAuthn devices [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22506) in GitLab 13.4 [with a flag](../../../administration/feature_flags.md) named `webauthn`. Disabled by default. +> - WebAuthn devices [enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/232671) in GitLab 14.6. +> - Optional one-time password authentication for WebAuthn devices [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/378844) in GitLab 15.10 [with a flag](../../../administration/feature_flags.md) named `webauthn_without_topt`. [Enabled on GitLab.com and self-managed by default](https://gitlab.com/gitlab-org/gitlab/-/issues/232671). FLAG: -On self-managed GitLab, by default this feature is available. To disable the feature, ask an administrator to +On self-managed GitLab, by default, WebAuthn devices are available. To disable the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `webauthn`. If you disable the WebAuthn feature flag after WebAuthn devices have been registered, these devices are not usable until you re-enable this feature. +On GitLab.com, WebAuthn devices are available. + +FLAG: +On self-managed GitLab, by default, optional one-time password authentication for WebAuthn devices is not available. To enable the feature, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `webauthn_without_totp`. On GitLab.com, this feature is available. -WebAuthn [supported by](https://caniuse.com/#search=webauthn): +WebAuthn is [supported by](https://caniuse.com/#search=webauthn) the following: -- The following desktop browsers: +- Desktop browsers: - Chrome - Edge - Firefox - Opera - Safari -- The following mobile browsers: +- Mobile browsers: - Chrome for Android - Firefox for Android - iOS Safari (since iOS 13.3) To set up 2FA with a WebAuthn-compatible device: +1. Optional. [Set up a one-time password](#enable-one-time-password). 1. Access your [**User settings**](../index.md#access-your-user-settings). 1. Select **Account**. 1. Select **Enable Two-Factor Authentication**. 1. Plug in your WebAuthn device. +1. Enter a device name and in GitLab 15.10 and later, your GitLab account password. + You might not need to enter this password if you have signed in through your + identity provider. 1. Select **Set up New WebAuthn Device**. 1. Depending on your device, you might have to press a button or touch a sensor. -A message displays indicating that your device was successfully set up. Recovery codes are not generated for WebAuthn -devices. +You should receive a message indicating that you successfully set up your device. + +When you set up 2FA with a WebAuthn-compatible device, that device is linked to +a specific browser on a specific computer. Depending on the browser and WebAuthn +device, you might be able to configure settings to use the WebAuthn device on a +different browser or computer. + +If this is the first time you have set up 2FA, you +must [download recovery codes](#recovery-codes) so you can recover access to your +account if you lose access. + +WARNING: +You can lose access to your account if you clear your browser data. ## Recovery codes @@ -272,11 +336,11 @@ these recovery codes to sign in to your account. WARNING: Each code can be used only once to sign in to your account. -We recommend copying and printing them, or downloading them using the **Download codes** button for storage in a safe +You should copy and print the codes, or use **Download codes** to download them for storage in a safe place. If you choose to download them, the file is called `gitlab-recovery-codes.txt`. NOTE: -Recovery codes are not generated for U2F or WebAuthn devices. +Recovery codes are not generated for WebAuthn devices. If you lose the recovery codes, or want to generate new ones, you can use either: @@ -302,18 +366,7 @@ and you're presented with a second prompt, depending on which type of 2FA you've ### Sign in using a one-time password -When asked, enter the pin from your one time password authenticator's application or a recovery code to sign in. - -### Sign in using a U2F device - -To sign in by using a U2F device: - -1. Select **Login via U2F Device**. -1. A light begins blinking on your device. Activate it by touching/pressing - its button. - -A message displays indicating that your device responded to the authentication request, and you're automatically signed -in. +When asked, enter the pin from your one-time password authenticator's application or a recovery code to sign in. ### Sign in using a WebAuthn device @@ -333,7 +386,7 @@ To disable 2FA: 1. Under **Register Two-Factor Authenticator**, enter your current password and select **Disable two-factor authentication**. -This clears all your 2FA registrations, including mobile applications and U2F or WebAuthn devices. +This clears all your 2FA registrations, including mobile applications and WebAuthn devices. ## Recovery options @@ -412,18 +465,18 @@ a GitLab global administrator disable 2FA for your account: ## Information for GitLab administrators **(FREE SELF)** - Take care that 2FA keeps working after [restoring a GitLab backup](../../../raketasks/backup_restore.md). -- To ensure 2FA authorizes correctly with a time-based one time passwords (TOTP) server, synchronize your GitLab +- To ensure 2FA authorizes correctly with a time-based one-time password (TOTP) server, synchronize your GitLab server's time using a service like NTP. Otherwise, authorization can always fail because of time differences. -- The GitLab U2F and WebAuthn implementation does _not_ work when the GitLab instance is accessed from multiple hostnames - or FQDNs. Each U2F or WebAuthn registration is linked to the _current hostname_ at the time of registration, and +- The GitLab WebAuthn implementation does _not_ work when the GitLab instance is accessed from multiple hostnames + or FQDNs. Each WebAuthn registration is linked to the _current hostname_ at the time of registration, and cannot be used for other hostnames or FQDNs. For example, if a user is trying to access a GitLab instance from `first.host.xyz` and `second.host.xyz`: - - The user signs in by using `first.host.xyz` and registers their U2F key. - - The user signs out and attempts to sign in by using `first.host.xyz` - U2F authentication succeeds. - - The user signs out and attempts to sign in by using `second.host.xyz` - U2F authentication fails, because - the U2F key has only been registered on `first.host.xyz`. + - The user signs in by using `first.host.xyz` and registers their WebAuthn key. + - The user signs out and attempts to sign in by using `first.host.xyz` - WebAuthn authentication succeeds. + - The user signs out and attempts to sign in by using `second.host.xyz` - WebAuthn authentication fails, because + the WebAuthn key has only been registered on `first.host.xyz`. - To enforce 2FA at the system or group levels see, [Enforce two-factor authentication](../../../security/two_factor_authentication.md). @@ -441,23 +494,25 @@ access token instead of a password. This error occurs in the following scenarios: - You have 2FA enabled and have attempted to authenticate with a username and - password. For 2FA-enabled users, a [personal access token](../personal_access_tokens.md) (PAT) - must be used instead of a password. To authenticate: - - Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required. - - [GitLab Container Registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT - with `read_registry` or `write_registry` scope is required. - - [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with - `read_registry` and `write_registry` scopes is required. + password. - You do not have 2FA enabled and have sent an incorrect username or password with your request. - You do not have 2FA enabled but an administrator has enabled the [enforce 2FA for all users](../../../security/two_factor_authentication.md#enforce-2fa-for-all-users) setting. - You do not have 2FA enabled, but an administrator has disabled the [password authentication enabled for Git over HTTP(S)](../../admin_area/settings/sign_in_restrictions.md#password-authentication-enabled) - setting. You can authenticate Git requests: - - Over HTTP(S) using a [personal access token](../personal_access_tokens.md). - - In your browser using [Git Credential Manager](#git-credential-manager). - - If you have configured LDAP, over HTTP(S) using an [LDAP password](../../../administration/auth/ldap/index.md). + setting. + +Instead you can authenticate: + +- Using a [personal access token](../personal_access_tokens.md) (PAT): + - For Git requests over HTTP(S), a PAT with `read_repository` or `write_repository` scope is required. + - For [GitLab Container Registry](../../packages/container_registry/authenticate_with_container_registry.md) requests, a PAT + with `read_registry` or `write_registry` scope is required. + - For [Dependency Proxy](../../packages/dependency_proxy/index.md#authenticate-with-the-dependency-proxy) requests, a PAT with + `read_registry` and `write_registry` scopes is required. +- If you have configured LDAP, using an [LDAP password](../../../administration/auth/ldap/index.md) +- Using an [OAuth credential helper](#oauth-credential-helpers). ### Error: "invalid pin code" |