Troubleshooting two-factor authentication

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

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 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 password authentication enabled for Git over HTTP(S) setting is not active.

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.

Go to Settings > System > Date & time.
Turn on Set time automatically. If the setting is already on, turn it off, wait a few seconds, and turn it on again.

Go to Settings > General > Date & Time.
Turn on Set Automatically. If the setting is already on, turn it off, wait a few seconds, and turn it on again.

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.

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:

On the GitLab sign-in page, enter your username or email, and password.
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:

Access your User settings.
Select Account > Two-Factor Authentication (2FA).
Select Manage two-factor authentication.
In the Disable two-factor authentication section, select Regenerate recovery codes.
In the dialog, enter your current password and select Regenerate recovery codes.

Every time you regenerate 2FA recovery codes, save them. You can’t use any previously created 2FA codes.

Regenerate recovery codes with SSH

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

You cannot use gitlab-sshd to regenerate recovery codes.

To regenerate recovery codes with SSH:

In a terminal, run:
```
ssh git@gitlab.com 2fa_recovery_codes
```
On GitLab Self-Managed instances, replace gitlab.com with the GitLab server hostname (gitlab.example.com).
On the confirmation message, enter yes.
Save the recovery codes that GitLab generates. Your previous recovery codes are no longer valid.
On the sign-in page, enter your username or email, and password.
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.

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.
GitLab recommends using recovery codes as your primary recovery method. Make sure you save your recovery codes when you enable 2FA.

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

Reset 2FA on your account

Tier: Premium, Ultimate
Offering: GitLab.com

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:

Go to GitLab Support.
Select Submit a Ticket.
Sign in with your GitLab Support account. Your support account is different from your GitLab account and is not impacted by your 2FA issue.
In the issue dropdown list, select GitLab.com user accounts and login issues.
Complete the fields in the support form.
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.