GitHub Desktop mfa

• Use personal access tokens with two-factor authentication
• Enable two-factor authentication
  • Enable one-time password
  • Enable one-time password using FortiAuthenticator
  • Enable one-time password using FortiToken Cloud
  • Set up a U2F device
  • Set up a WebAuthn device
• Recovery codes
  • Regenerate two-factor authentication recovery codes
• Sign in with two-factor authentication enabled
  • Sign in using a one-time password
  • Sign in using a U2F device
  • Sign in using a WebAuthn device
• Disable two-factor authentication
• Recovery options
  • Use a saved recovery code
  • Generate new recovery codes using SSH
  • Have two-factor authentication disabled on your account
• Information for GitLab administrators
• Troubleshooting

Two-factor authentication

Two-factor authentication [2FA] provides an additional level of security to your GitLab account. For others to access your account, they would need your username and password and access to your second factor of authentication.

GitLab supports as a second factor of authentication:

• Time-based one-time passwords [TOTP]. 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. Youre prompted to activate your U2F or 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.

Use personal access tokens with two-factor authentication

When 2FA is enabled, you cant use your password to authenticate with Git over HTTPS or the GitLab API. You must use a personal access token instead.

Enable two-factor authentication

You can enable 2FA:

• Using a one-time password authenticator. After you enable 2FA, back up your recovery codes.
• Using a U2F or WebAuthn device.

In GitLab 14.3 and later, your account email must be confirmed to enable 2FA.

Enable one-time password

To enable 2FA with a one-time password:

1. In GitLab:
   1. Access your User settings.
   2. Select Account.
   3. Select Enable Two-factor Authentication.
2. On your device [usually your phone]:
   1. Install a compatible application. For example:
      • Authy
      • Duo Mobile
      • LastPass Authenticator
      • Authenticator
      • andOTP
      • Google Authenticator
      • Microsoft Authenticator
      • SailOTP
   2. In the application, add a new entry in one of two ways:
      • Scan the code displayed by GitLab with your devices camera to add the entry automatically.
      • Enter the details provided to add the entry manually.
3. In GitLab:
   1. Enter the six-digit pin number from the entry on your device into Pin code.
   2. Enter your current password.
   3. Select Submit.

If you entered the correct pin, GitLab displays a list of recovery codes. Download them and keep them in a safe place.

Enable one-time password using FortiAuthenticator

You can use FortiAuthenticator as a one-time password [OTP] provider in GitLab. Users must:

• Exist in both FortiAuthenticator and GitLab with the same username.
• Have FortiToken configured in FortiAuthenticator.

You need a username and access token for FortiAuthenticator. The access_token shown below is the FortAuthenticator access key. To get the token, see the REST API Solution Guide at Fortinet Document Library. GitLab 13.5 has been tested with FortAuthenticator version 6.2.0.

Configure FortiAuthenticator in GitLab. On your GitLab server:

1. Open the configuration file.

   For Omnibus GitLab:

   sudo editor /etc/gitlab/gitlab.rb

   For installations from source:

   cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml

2. Add the provider configuration:

   For Omnibus package:

   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'] = '' gitlab_rails['forti_authenticator_access_token'] = 's3cr3t'

   For installations from source:

   forti_authenticator: enabled: true host: forti_authenticator.example.com port: 443 username: access_token: s3cr3t
3. Save the configuration file.
4. Reconfigure [Omnibus GitLab] or restart [GitLab installed from source].

Enable one-time password using FortiToken Cloud

You can use FortiToken Cloud as a one-time password [OTP] provider in GitLab. Users must:

• Exist in both FortiToken Cloud and GitLab with the same username.
• Have FortiToken configured in FortiToken Cloud.

You need a client_id and client_secret to configure FortiToken Cloud. To get these, see the REST API Guide at Fortinet Document Library.

Configure FortiToken Cloud in GitLab. On your GitLab server:

1. Open the configuration file.

   For Omnibus GitLab:

   sudo editor /etc/gitlab/gitlab.rb

   For installations from source:

   cd /home/git/gitlab sudo -u git -H editor config/gitlab.yml

2. Add the provider configuration:

   For Omnibus package:

   gitlab_rails['forti_token_cloud_enabled'] = true gitlab_rails['forti_token_cloud_client_id'] = '' gitlab_rails['forti_token_cloud_client_secret'] = ''

   For installations from source:

   forti_token_cloud: enabled: true client_id: YOUR_FORTI_TOKEN_CLOUD_CLIENT_ID client_secret: YOUR_FORTI_TOKEN_CLOUD_CLIENT_SECRET
3. Save the configuration file.
4. Reconfigure [Omnibus GitLab] or restart [GitLab installed from source].

Set up a U2F device

GitLab officially supports YubiKey U2F devices, but users have successfully used SoloKeys and Google Titan Security Key.

U2F is supported by the following desktop browsers:

• Chrome
• Edge
• Opera

• Firefox 67+. For Firefox 47-66:

  1. Enable the FIDO U2F API in about:config.
  2. 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.
2. Select Account.
3. Select Enable Two-Factor Authentication.
4. Connect your U2F device.
5. Select on Set up New U2F Device.
6. 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

WebAuthn supported by:

• The following desktop browsers:
  • Chrome
  • Edge
  • Firefox
  • Opera
  • Safari
• 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. Access your User settings.
2. Select Account.
3. Select Enable Two-Factor Authentication.
4. Plug in your WebAuthn device.
5. Select Set up New WebAuthn Device.
6. 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.

Recovery codes

Immediately after successfully enabling 2FA with a one-time password, youre prompted to download a set of generated recovery codes. If 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 recommend 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.

If you lose the recovery codes, or want to generate new ones, you can use either:

• The 2FA account settings page.
• SSH.

Regenerate two-factor authentication recovery codes

To regenerate 2FA recovery codes, you need access to a desktop browser:

1. Access your User settings.
2. Select Account > Two-Factor Authentication [2FA].
3. If youve already configured 2FA, select Manage two-factor authentication.
4. In the Register Two-Factor Authenticator pane, enter your current password and select Regenerate recovery codes.

Sign in with two-factor authentication enabled

Signing in with 2FA enabled is only slightly different than the normal sign-in process. Enter your username and password and youre presented with a second prompt, depending on which type of 2FA youve enabled.

Sign in using a one-time password

When asked, enter the pin from your one time password authenticators 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.
2. 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 youre automatically signed in.

Sign in using a WebAuthn device

In supported browsers, you should be automatically prompted to activate your WebAuthn device [for example, by touching or pressing its button] after entering your credentials.

A message displays indicating that your device responded to the authentication request and youre automatically signed in.

Disable two-factor authentication

To disable 2FA:

1. Access your User settings.
2. Select Account.
3. Select Manage two-factor authentication.
4. 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.

Support Team support for disabling 2FA is limited, depending on your subscription level. For more information, see the Account Recovery section of our website.

Recovery options

If you dont have access to your code generation device, you can recover access to your account:

• Use a saved recovery code, if you saved them when you enabled two-factor authentication.
• Generate new recovery codes using SSH, if you didnt save your original recovery codes but have an SSH key.
• Have 2FA disabled on your account, if you dont have your recovery codes or an SSH key.

Use a saved recovery code

To use a recovery code:

1. Enter your username or email, and password, on the GitLab sign-in page.
2. 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 2FA. If you added an SSH key to your GitLab account, you can generate a new set of recovery codes with SSH:

1. In a terminal, run:

   ssh 2fa_recovery_codes

   On self-managed instances, replace gitlab.com in the command above with the GitLab server hostname [gitlab.example.com].

2. You are prompted to confirm that you want to generate new codes. This process invalidates previously-saved codes. For example:

   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.

3. Go to the GitLab sign-in page and enter your username or 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, immediately set up 2FA with a new device.

Have two-factor authentication disabled on your account

If other methods are unavailable, submit a support ticket to request a GitLab global administrator disable 2FA for your account:

• Only the owner of the account can make this request.
• This service is only available for accounts that have a GitLab.com subscription. For more information, see our blog post.
• Disabling this setting temporarily leaves your account in a less secure state. You should sign in and re-enable two-factor authentication as soon as possible.

Information for GitLab administrators

• Take care that 2FA keeps working after restoring a GitLab backup.
• To ensure 2FA authorizes correctly with a time-based one time passwords [TOTP] server, synchronize your GitLab servers 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 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.
• To enforce 2FA at the system or group levels see, Enforce two-factor authentication.

Troubleshooting

If you receive an invalid pin code error, this can indicate that there is a time sync issue between the authentication application and the GitLab instance itself. To avoid the time sync issue, enable time synchronization in the device that generates the codes. For example:

• For Android [Google Authenticator]:
  1. Go to the Main Menu in Google Authenticator.
  2. Select Settings.
  3. Select the Time correction for the codes.
  4. Select Sync now.
• For iOS:
  1. Go to Settings.
  2. Select General.
  3. Select Date & Time.
  4. Enable Set Automatically. If its already enabled, disable it, wait a few seconds, and re-enable.