GitLab 2FA Lockout: How My Local SSH Key Saved the Day

Two-factor authentication (2FA) is a security measure that requires users to provide two forms of identification when logging into an account. One such user experienced a lockout on their GitLab account after attempting to change the backup password using their authenticator app. Stranded without access, they had to disable 2FA and re-enable it using a different app.

While re-enabling 2FA proved straightforward since they were still logged into most of their accounts, the user found themselves in a predicament when they realized they did not have their GitLab recovery codes. GitLab provides two methods to retrieve access: either via email or by generating new recovery codes using an SSH key linked to the account. The latter option proved to be a lifesaver for this individual.

When setting up GitLab in their local environment, the user always creates an SSH key for authentication and commit signing. They documented this process in a previous article. To obtain new recovery codes without an email verification code, the user must check the SSH keys on their machine. By listing files in the ~/.ssh directory, they identified key files such as id_rsa or id_ed25519.

To generate new recovery codes, the user executed the command "ssh -i ~/.ssh/id_ed25519 git@gitlab.com 2fa_recovery_codes". They replaced "id_ed25519" with the name of their SSH key file. Once they had copied a recovery code, they signed in using their username and password, entering the recovery code when prompted. Now back in their GitLab account, they disabled 2FA and re-enabled it, ensuring they saved the recovery codes in a secure location for future reference.