Troubleshooting two-factor authentication

Error: HTTP Basic: Access denied. If a password was provided for Git authentication ...

When making a request, you might get an error that states:

HTTP Basic: Access denied. If a password was provided for Git authentication,
the password was incorrect or you're required to use a token instead of a password.
If a token was provided, it was either incorrect, expired, or improperly scoped.

This error occurs when:

• You have enabled 2FA and attempted to authenticate with a username and password.
• You are on GitLab.com and your account requires 2FA (see email OTP troubleshooting).
• You have not enabled 2FA and attempted to authenticate with an incorrect username or password.
• You have not enabled 2FA and the enforce 2FA for all users setting is active.
• You have not enabled 2FA and the Allow password authentication for Git over HTTP(S) checkbox is not selected.

To resolve this error:

• Use a personal access token with the correct scopes:
  • For Git requests over HTTP(S): read_repository or write_repository
  • For GitLab container registry requests: read_registry or write_registry
  • For dependency proxy requests: read_registry and write_registry
• If you configured LDAP, use an LDAP password.
• Use an OAuth credential helper.

Error: invalid pin code

An invalid pin code error can indicate that there is a time sync issue between the authentication application and the GitLab instance itself.

To resolve this issue, turn on time synchronization for the device that generates your 2FA codes.

Error: Permission denied (publickey) when generating recovery codes

You might get an error that states Permission denied (publickey).

This issue occurs if you are using a non-default SSH key pair file path and attempt to generate recovery codes using SSH.

To resolve this, configure SSH to point to a different directory using ssh-agent.

Email OTP troubleshooting

When working with email OTP, you might encounter the following issues.

Enhanced authentication banner and passcode requirement

The Enhanced Authentication Coming Soon banner signals that GitLab will begin to enforce email one-time passcodes for your account at password-based sign-in. Users who sign in with SSO or who have 2FA already configured are unaffected.

This banner appears 14 days before enforcement. 7 days before enforcement, GitLab sends you a one-time passcode at each password-based sign-in. You can skip passcode entry during this period.

When the enforcement date passes, you must enter a one-time passcode at every password-based sign-in. To avoid being locked out, ensure you can access your primary email address, or change your primary email address.

Didn’t receive email verification code or code has expired

Check your spam folder. On GitLab.com, emails are sent from gitlab@mg.gitlab.com and can be verified as genuine.

If your code expires, you can request a new code. From the sign-in page, select Resend code.

Cannot access your email address

If you cannot access your primary email address, use another email address associated with your account. From the sign-in page, select Send a code to another address associated with this account.

If you cannot access any associated email address:

• If you previously configured SSO, sign in with SSO instead of a username and password.
• If you are a GitLab.com enterprise user, ask your group owner to change your email address.
• On GitLab Self-Managed, contact your GitLab administrator.
• Contact GitLab Support.

Email OTP cannot be enabled or disabled

You cannot disable email OTP if:

• Your instance requires 2FA and you have not registered an OTP authenticator or a WebAuthn device.
• Your account is scheduled for automatic enablement at a future date.

You cannot enable email OTP if:

• Your group, instance, or admin policy requires you to use an OTP authenticator or WebAuthn device.
• Your account uses an external identity provider.
• Your account is scheduled for automatic enablement at a future date.

Recovery options and 2FA reset

Use a recovery code

When you enabled a one-time password (OTP) authenticator, GitLab provided you with a series of recovery codes. You can use these codes to sign in to your account.

To use a recovery code:

1. On the GitLab sign-in page, enter your username or email, and password.
2. When prompted for a two-factor code, enter a recovery code.

After you use a recovery code, you cannot use the same code again. Your other recovery codes remain valid.

Regenerate recovery codes with the UI

If you can still access your account, you can regenerate your recovery codes through your user settings.

To regenerate recovery codes with the UI:

1. In the upper-right corner, select your avatar.
2. Select Edit profile.
3. In the left sidebar, select Access > Password and authentication.
4. In the Recovery codes section, select Regenerate recovery codes.
5. In the dialog, enter your current password and select Regenerate recovery codes.

Regenerate recovery codes with SSH

If you added an SSH key to your GitLab account, you can regenerate your recovery codes with SSH.

Prerequisites:

• Access to the private SSH key associated with the SSH public key registered to your GitLab account.

To regenerate recovery codes with SSH:

1. In the terminal, verify SSH agent is running on your device.

   • On macOS and Linux, run the following command:

     eval "$(ssh-agent -s)"

   • On Microsoft Windows, run the following command in PowerShell:

     Set-Service -Name ssh-agent -StartupType Automatic; Start-Service ssh-agent

     For more information, see SSH setup instructions for Windows.

2. Load the private key into SSH agent with the following command:

   • On macOS and Linux, run the following command:

     ssh-add <directory to private SSH key>

   For more information, see Use SSH keys in another directory.

3. Open an SSH connection with the following command:

   ssh git@gitlab.com 2fa_recovery_codes

   On GitLab Self-Managed instances, replace gitlab.com with the GitLab server hostname (gitlab.example.com).

4. On the confirmation message, enter yes.

5. Save the recovery codes that GitLab generates. Your previous recovery codes are no longer valid.

6. On the sign-in page, enter your username or email, and password.

7. When prompted for a two-factor code, enter one of your new recovery codes.

After signing in, immediately set up 2FA with a new device.

Restore 2FA codes from authenticator backup

In addition to the GitLab recovery codes, many authenticator apps offer their own backup and recovery methods. If you lose your device, you may be able to restore your 2FA codes by logging into your authenticator app on a new device, provided you enabled backup features beforehand.

Prerequisites:

• You must enable your authenticator backup features before you lose access to your device.

GitLab Support cannot assist with recovery issues related to third-party authenticator apps.

For more information, see the documentation for your specific authenticator app. Documentation for common authenticators is available through the following locations:

• Microsoft Authenticator
• Google Authenticator
• Authy
• 1Password

Reset 2FA on your account

If the previous recovery options do not work, you can create a support request to disable 2FA for your account. This service is only available for accounts with a GitLab.com subscription.

GitLab Support cannot reset 2FA for Free accounts. If you cannot recover your 2FA method, you will be permanently locked out of your account and must create a new one. For more information, see the blog announcement.

To create a support request:

1. Go to GitLab Support.
2. Select Submit a Ticket.
3. Sign in with your GitLab Support account. Your support account is different from your GitLab account and is not impacted by your 2FA issue.
4. In the issue dropdown list, select GitLab.com user accounts and login issues.
5. Complete the fields in the support form.
6. Select Submit.

After you regain access to your account, re-enable 2FA as soon as possible to keep your account secure.

Reset 2FA for enterprise users

If you are a top-level group Owner on a paid plan, you can disable 2FA for enterprise users. For more information, see disable 2FA for enterprise users.