519 lines
19 KiB
Markdown
519 lines
19 KiB
Markdown
---
|
|
type: howto
|
|
stage: Manage
|
|
group: Access
|
|
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
|
|
---
|
|
|
|
# Two-factor authentication **(FREE)**
|
|
|
|
Two-factor authentication (2FA) provides an additional level of security to your
|
|
GitLab account. After being enabled, in addition to supplying your username and
|
|
password to sign in, you are 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 sign in to your account
|
|
is to know your username and password _and_ have access to your one-time
|
|
password secret.
|
|
|
|
## Overview
|
|
|
|
NOTE:
|
|
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) and WebAuthn (experimental) devices as the second factor
|
|
of authentication. After being enabled, in addition to supplying your username
|
|
and password to sign in, you're prompted to activate your U2F / WebAuthn device
|
|
(usually by pressing a button on it) which performs secure authentication on
|
|
your behalf.
|
|
|
|
It's highly recommended that you set up 2FA with both a [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 multiple ways to enable two-factor authentication: by using a one-time
|
|
password authenticator or a U2F / WebAuthn device.
|
|
|
|
### One-time password
|
|
|
|
To enable 2FA:
|
|
|
|
1. **In GitLab:**
|
|
1. Sign in to your GitLab account.
|
|
1. Go to your [**User settings**](../index.md#access-your-user-settings).
|
|
1. Go to **Account**.
|
|
1. Select **Enable Two-factor Authentication**.
|
|
1. **On your device (usually your phone):**
|
|
1. Install a compatible application, like:
|
|
- [Authy](https://authy.com/)
|
|
- [Duo Mobile](https://duo.com/product/multi-factor-authentication-mfa/duo-mobile-app)
|
|
- [LastPass](https://lastpass.com/auth/)
|
|
- [Authenticator](https://mattrubin.me/authenticator/)
|
|
- [andOTP](https://github.com/andOTP/andOTP)
|
|
- [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en)
|
|
- [SailOTP](https://openrepos.net/content/seiichiro0185/sailotp)
|
|
1. In the application, add a new entry in one of two ways:
|
|
- Scan the code presented in GitLab with your device's camera to add the
|
|
entry automatically.
|
|
- Enter the details provided to add the entry manually.
|
|
1. **In GitLab:**
|
|
1. Enter the six-digit pin number from the entry on your device into the **Pin
|
|
code** field.
|
|
1. Select **Submit**.
|
|
|
|
If the pin you entered was correct, a message displays indicating that
|
|
two-factor authentication has been enabled, and you're shown a list
|
|
of [recovery codes](#recovery-codes). Be sure to download them and keep them
|
|
in a safe place.
|
|
|
|
### 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 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>))
|
|
```
|
|
|
|
### One-time password via FortiToken Cloud
|
|
|
|
> - Introduced in [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/212313).
|
|
> - It's deployed behind a feature flag, 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-fortitoken-cloud-integration).
|
|
|
|
WARNING:
|
|
This feature might not be available to you. Check the **version history** note above for details.
|
|
|
|
You can use FortiToken Cloud as an OTP provider in GitLab. Users must exist in
|
|
both FortiToken Cloud and GitLab with the exact same username, and users must
|
|
have FortiToken configured in FortiToken Cloud.
|
|
|
|
You'll also need a `client_id` and `client_secret` to configure FortiToken Cloud.
|
|
To get these, see the `REST API Guide` at
|
|
[`Fortinet Document Library`](https://docs.fortinet.com/document/fortitoken-cloud/latest/rest-api).
|
|
|
|
First configure FortiToken Cloud 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_token_cloud_enabled'] = true
|
|
gitlab_rails['forti_token_cloud_client_id'] = '<your_fortinet_cloud_client_id>'
|
|
gitlab_rails['forti_token_cloud_client_secret'] = '<your_fortinet_cloud_client_secret>'
|
|
```
|
|
|
|
For installations from source:
|
|
|
|
```yaml
|
|
forti_token_cloud:
|
|
enabled: true
|
|
client_id: YOUR_FORTI_TOKEN_CLOUD_CLIENT_ID
|
|
client_secret: YOUR_FORTI_TOKEN_CLOUD_CLIENT_SECRET
|
|
```
|
|
|
|
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 or disable FortiToken Cloud integration
|
|
|
|
FortiToken Cloud integration 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(:forti_token_cloud, User.find(<user ID>))
|
|
```
|
|
|
|
To disable it:
|
|
|
|
```ruby
|
|
Feature.disable(:forti_token_cloud, User.find(<user ID>))
|
|
```
|
|
|
|
### U2F device
|
|
|
|
> Introduced in [GitLab 8.9](https://about.gitlab.com/blog/2016/06/22/gitlab-adds-support-for-u2f/).
|
|
|
|
GitLab officially only supports [YubiKey](https://www.yubico.com/products/)
|
|
U2F devices, but users have successfully used [SoloKeys](https://solokeys.com/)
|
|
or [Google Titan Security Key](https://cloud.google.com/titan-security-key).
|
|
|
|
The U2F workflow is [supported by](https://caniuse.com/#search=U2F) the
|
|
following desktop browsers:
|
|
|
|
- Chrome
|
|
- Edge
|
|
- Firefox 67+
|
|
- Opera
|
|
|
|
NOTE:
|
|
For Firefox 47-66, you can enable the FIDO U2F API in
|
|
[`about:config`](https://support.mozilla.org/en-US/kb/about-config-editor-firefox).
|
|
Search for `security.webauth.u2f` and double click on it to toggle to `true`.
|
|
|
|
To set up 2FA with a U2F device:
|
|
|
|
1. Sign in to your GitLab account.
|
|
1. Go to your [**User settings**](../index.md#access-your-user-settings).
|
|
1. Go to **Account**.
|
|
1. Click **Enable Two-Factor Authentication**.
|
|
1. Connect your U2F device.
|
|
1. Click on **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.
|
|
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). **(FREE SELF)**
|
|
|
|
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 [**User settings**](../index.md#access-your-user-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.
|
|
|
|
A message displays, indicating that your device was successfully set up.
|
|
Recovery codes are not generated for WebAuthn devices.
|
|
|
|
## Recovery codes
|
|
|
|
NOTE:
|
|
Recovery codes are not generated for U2F / WebAuthn devices.
|
|
|
|
WARNING:
|
|
Each code can be used only once to sign in to your account.
|
|
|
|
Immediately after successfully enabling two-factor authentication, you're
|
|
prompted to download a set of generated recovery codes. Should you ever lose access
|
|
to your one-time password authenticator, you can use one of these recovery codes to sign in to
|
|
your account. We suggest copying and printing them, or downloading them using
|
|
the **Download codes** button for storage in a safe place. If you choose to
|
|
download them, the file is called `gitlab-recovery-codes.txt`.
|
|
|
|
The UI now includes **Copy codes** and **Print codes** buttons, for your convenience.
|
|
[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267730) in GitLab 13.7.
|
|
|
|
If you lose the recovery codes or just want to generate new ones, you can do so
|
|
from the [two-factor authentication account settings page](#regenerate-2fa-recovery-codes) or
|
|
[using SSH](#generate-new-recovery-codes-using-ssh).
|
|
|
|
## Signing in with 2FA Enabled
|
|
|
|
Signing in with 2FA enabled is only slightly different than the normal sign-in process.
|
|
Enter your username and password credentials as you normally would, and you're
|
|
presented with a second prompt, depending on which type of 2FA you've enabled.
|
|
|
|
### Sign in by 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 by using a U2F device
|
|
|
|
To sign in by using a U2F device:
|
|
|
|
1. Click **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.
|
|
|
|
### Sign in by using a 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.
|
|
|
|
A message displays, indicating that your device responded to the authentication
|
|
request and you're automatically signed in.
|
|
|
|
## Disabling 2FA
|
|
|
|
If you ever need to disable 2FA:
|
|
|
|
1. Sign in to your GitLab account.
|
|
1. Go to your [**User settings**](../index.md#access-your-user-settings).
|
|
1. Go to **Account**.
|
|
1. Click **Disable**, under **Two-Factor Authentication**.
|
|
|
|
This clears all your two-factor authentication registrations, including mobile
|
|
applications and U2F / WebAuthn devices.
|
|
|
|
Support for disabling 2FA is limited, depending on your subscription level. For more information, see the
|
|
[Account Recovery](https://about.gitlab.com/support/#account-recovery) section of our website.
|
|
|
|
## Personal access tokens
|
|
|
|
When 2FA is enabled, you can no longer use your normal account password to
|
|
authenticate with Git over HTTPS on the command line or when using
|
|
the [GitLab API](../../../api/README.md). You must use a
|
|
[personal access token](../personal_access_tokens.md) instead.
|
|
|
|
## Recovery options
|
|
|
|
To disable two-factor authentication on your account (for example, if you
|
|
have lost your code generation device) you can:
|
|
|
|
- [Use a saved recovery code](#use-a-saved-recovery-code).
|
|
- [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh).
|
|
- [Regenerate 2FA recovery codes](#regenerate-2fa-recovery-codes).
|
|
- [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account).
|
|
|
|
### Use a saved recovery code
|
|
|
|
Enabling two-factor authentication for your account generated several recovery
|
|
codes. If you saved these codes, you can use one of them to sign in.
|
|
|
|
To use a recovery code, enter your username/email and password on the GitLab
|
|
sign-in page. When prompted for a two-factor code, enter the recovery code.
|
|
|
|
After you use a recovery code, you cannot re-use it. You can still use the other
|
|
recovery codes you saved.
|
|
|
|
### Generate new recovery codes using SSH
|
|
|
|
Users often forget to save their recovery codes when enabling two-factor
|
|
authentication. If an SSH key is added to your GitLab account, you can generate
|
|
a new set of recovery codes with SSH:
|
|
|
|
1. Run:
|
|
|
|
```shell
|
|
ssh git@gitlab.com 2fa_recovery_codes
|
|
```
|
|
|
|
NOTE:
|
|
On self-managed instances, replace **`gitlab.com`** in the command above
|
|
with the GitLab server hostname (`gitlab.example.com`).
|
|
|
|
1. You are prompted to confirm that you want to generate new codes.
|
|
Continuing this process invalidates previously saved codes:
|
|
|
|
```shell
|
|
Are you sure you want to generate new two-factor recovery codes?
|
|
Any existing recovery codes you saved will be invalidated. (yes/no)
|
|
|
|
yes
|
|
|
|
Your two-factor authentication recovery codes are:
|
|
|
|
119135e5a3ebce8e
|
|
11f6v2a498810dcd
|
|
3924c7ab2089c902
|
|
e79a3398bfe4f224
|
|
34bd7b74adbc8861
|
|
f061691d5107df1a
|
|
169bf32a18e63e7f
|
|
b510e7422e81c947
|
|
20dbed24c5e74663
|
|
df9d3b9403b9c9f0
|
|
|
|
During sign in, use one of the codes above when prompted for your
|
|
two-factor code. Then, visit your Profile Settings and add a new device
|
|
so you do not lose access to your account again.
|
|
```
|
|
|
|
1. Go to the GitLab sign-in page and enter your username/email and password.
|
|
When prompted for a two-factor code, enter one of the recovery codes obtained
|
|
from the command-line output.
|
|
|
|
After signing in, visit your **User settings > Account** immediately to set
|
|
up two-factor authentication with a new device.
|
|
|
|
### Regenerate 2FA recovery codes
|
|
|
|
To regenerate 2FA recovery codes, you need access to a desktop browser:
|
|
|
|
1. Navigate to GitLab.
|
|
1. Sign in to your GitLab account.
|
|
1. Go to your [**User settings**](../index.md#access-your-user-settings).
|
|
1. Select **Account > Two-Factor Authentication (2FA)**.
|
|
1. If you've already configured 2FA, click **Manage two-factor authentication**.
|
|
1. In the **Register Two-Factor Authenticator** pane, click **Regenerate recovery codes**.
|
|
|
|
NOTE:
|
|
If you regenerate 2FA recovery codes, save them. You can't use any previously created 2FA codes.
|
|
|
|
### Ask a GitLab administrator to disable two-factor authentication on your account
|
|
|
|
If you cannot use a saved recovery code or generate new recovery codes, ask a
|
|
GitLab global administrator to disable two-factor authentication for your
|
|
account. This temporarily leaves your account in a less secure state.
|
|
Sign in and re-enable two-factor authentication as soon as possible.
|
|
|
|
## Note to GitLab administrators
|
|
|
|
- You need to take special care to that 2FA keeps working after
|
|
[restoring a GitLab backup](../../../raketasks/backup_restore.md).
|
|
- To ensure 2FA authorizes correctly with TOTP server, you may want to ensure
|
|
your GitLab server's time is synchronized via a service like NTP. Otherwise,
|
|
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 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`:
|
|
|
|
- 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`.
|
|
|
|
- To enforce 2FA at the system or group levels see [Enforce Two-factor Authentication](../../../security/two_factor_authentication.md).
|
|
|
|
## Enable or disable WebAuthn **(FREE SELF)**
|
|
|
|
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.
|
|
|
|
Most authentication apps have a feature in the settings for syncing the time for the codes themselves. For Google Authenticator for example, go to `Settings > Time correction for codes`.
|
|
|
|
<!-- ## Troubleshooting
|
|
|
|
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
|
|
one might have when setting this up, or when something is changed, or on upgrading, it's
|
|
important to describe those, too. Think of things that may go wrong and include them here.
|
|
This is important to minimize requests for support, and to avoid doc comments with
|
|
questions that you know someone might ask.
|
|
|
|
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
|
|
If you have none to add when creating a doc, leave this section in place
|
|
but commented out to help encourage others to add to it in the future. -->
|