GitLab Multi-Factor Authentication¶

To enhance security, GitLab provides an option to enable Multi-Factor Authentication (MFA, also referred to as Two-factor Authentication or 2FA). This adds an extra layer of security by requiring a second form of verification in addition to your password.
MFA is not currently mandatory but is highly recommended for all users and it's likely to become a requirement on BEAR GitLab in the future.

Enabling multi-factor authentication¶

Warning

Once you have enabled MFA on your BEAR GitLab account you will no longer be able to use your username and password for authentication with git remotes. Instead, you will need to use a Personal Access Token (PAT) for command-line (CLI) access. See the information on this page for details.

Log in to your BEAR GitLab account at https://gitlab.bham.ac.uk using your University of Birmingham credentials.
Click your profile picture in the top left corner and select Preferences.
In the left sidebar, click Account.
Under the Two-factor authentication section, click Enable two-factor authentication.
Follow the instructions to set up your preferred method of MFA, such as using an authenticator app (e.g. Google Authenticator, Authy).

Generating a Personal Access Token¶

Once you have enabled MFA you need to generate Personal Access Tokens (PATs) for non-web access to BEAR GitLab, such as command-line (CLI) access with git or using graphical code editors with GitLab integration.

To generate a Personal Access Token, navigate to the following URL after logging in to BEAR GitLab and follow the instructions in the GitLab documentation:
https://gitlab.bham.ac.uk/-/user_settings/personal_access_tokens

Note that you need to select the appropriate scope(s) for your token – please select the write_repository scope at a minimum, which allows you to pull and also push changes to your repositories.

Token expiration date

When creating a Personal Access Token you need to set an expiration date. The default is 30 days from the date of creation but this can be set to a longer period if required.

Multi-factor authentication and graphical code editors¶

Code editors such as Visual Studio Code (VS Code) often have extensions that provide GitLab integration. These extensions handle token-based authentication and prompt you to enter your Personal Access Token (PAT) when you first connect to a BEAR GitLab repository. You can then paste in an appropriate PAT to authenticate.

See the documentation for your specific code editor or extension for more details.

Multi-factor authentication and command line (CLI) access¶

If you try to use your username and password with git to authenticate with a BEAR GitLab remote after enabling MFA, you will receive an error message similar to the following:

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

This is because git remotes don't support MFA prompts.

Personal Access Token storage setup¶

BlueBEAR login nodes have the tools installed (gpg, pass and Git Credential Manager) for storing your BEAR GitLab Personal Access Token (PAT) so you don't have to enter it every time you push or pull from a gitlab.bham.ac.uk repository via the CLI.
The setup process is outlined as follows. Note that you only need to do this once.

Create a GNU Privacy Guard (GPG) key if you don't already have one by executing the following command in your BlueBEAR shell:

This key is used to encrypt and decrypt items in your password store via pass.
```
gpg --gen-key
```
Follow the prompts to create your GPG key:
- Real name: Enter your full name and press Enter.
- Email address: Enter your University of Birmingham email address and press Enter.
Having entered your name and email address, you will see a summary similar to the following:
```
Real name: Taylor Test
Email address: t.t.test@bham.ac.uk
You selected this USER-ID:
    "Taylor Test <t.t.test@bham.ac.uk>"

Change (N)ame, (E)mail, or (O)kay/(Q)uit?
```
- Type the letter o and press Enter to confirm the details and proceed.
- Follow the prompt to enter a passphrase for your GPG key, which you need to remember.
  
  Password strength
  
  GPG doesn't enforce any specific password strength requirements but will warn you if your passphrase is considered weak.
After you have entered and confirmed your passphrase, GPG will generate your key. This can take some time, depending on the amount of entropy (randomness) available on the system. Once the key generation is complete, you will see a message similar to the following:
```
pub   rsa2048 2025-01-01 [SC] [expires: 2027-01-01]
    8XGAF3IKDD59A5IJ8CU0T8SPRYAWP5FWZHEAL7HL
uid                      Taylor Test <t.t.test@bham.ac.uk>
sub   rsa2048 2025-01-01 [E] [expires: 2027-01-01]
```
The 40-character string in the pub section is your GPG Key ID – in the example this is "8XGAF3IKDD59A5IJ8CU0T8SPRYAWP5FWZHEAL7HL". Make a note of this, as you will need it when initialising the password manager.

The password manager is initialised as follows:

pass init Your_GPG_Key_ID

Example pass init output

$ pass init 8XGAF3IKDD59A5IJ8CU0T8SPRYAWP5FWZHEAL7HL
mkdir: created directory '/rds/homes/t/test/.password-store/'
Password store initialized for 8XGAF3IKDD59A5IJ8CU0T8SPRYAWP5FWZHEAL7HL

Finally, configure git to use the Git Credential Manager by running the following commands:

Note

This example only configures the credential manager for gitlab.bham.ac.uk (BEAR GitLab).
It also assumes that the environment's username is the same as your University of Birmingham username. If this isn't the case, replace ${USER} with your University of Birmingham username in lowercase.
```
git config --global credential.gitlab.bham.ac.uk.helper /usr/local/bin/git-credential-manager
git config --global credential.gitlab.bham.ac.uk.username ${USER}
git config --global credential.gitlab.bham.ac.uk.credentialStore gpg
```

Using your Personal Access Token with Git¶

X11 forwarding

If you have X11 forwarding enabled in your SSH client, some of the prompts described in this section may appear in a pop-up window. If you don't have X11 forwarding enabled, the prompts appear in a terminal window as shown in the following examples.

Having completed the steps to configure the Git Credential Manager, you can now use your Personal Access Token (PAT) for command-line tool access to BEAR GitLab repositories.

The first time you connect to any gitlab.bham.ac.uk repository, for example by running git fetch or git pull, you are prompted to configure the credential manager to use your PAT. (1) Select the Personal access token option, enter your University of Birmingham username in lowercase (if it's not already populated) and paste in your generated PAT.

If you recently authenticated using a different method and already had credential caching enabled then run the following command to clear the cache before proceeding:
```
git credential-cache exit
```

Example terminal output and promptsExample X11 pop-up window

[testt@bear-pg-login06 my_bear_gitlab_repo]$ git fetch
warning: missing OAuth configuration for gitlab.bham.ac.uk - see https://aka.ms/gcm/gitlab for more information
Select an authentication method for 'https://gitlab.bham.ac.uk/':
1. Personal access token (default)
2. Username/password
option (enter for default): 1
Enter GitLab credentials for 'https://gitlab.bham.ac.uk/'...
Username: testt
Personal access token:

The following pop-up window appears if you have X11 forwarding enabled in your SSH client.

For subsequent access to gitlab.bham.ac.uk repositories, the credential manager will automatically use your stored Personal Access Token (PAT). You will need to enter the passphrase for your GPG key to unlock the token – once unlocked, the credential manager will cache the token for a period of time so you don't need to enter your passphrase every time.

Example GPG passphrase prompt

┌────────────────────────────────────────────────────────────────┐
│ Please enter the passphrase to unlock the OpenPGP secret key:  │
│ "Taylor Test <t.t.test@bham.ac.uk>"                            │
│ 2048-bit RSA key, ID KDD59A5IJ8XGAF3I,                         │
│ created 2025-01-01 (main key ID RYAWP5FWZHEAL7HL).             │
│                                                                │
│                                                                │
│ Passphrase: __________________________________________________ │
│                                                                │
│         <OK>                                    <Cancel>       │
└────────────────────────────────────────────────────────────────┘

Error: gpg: public key decryption failed

Depending on your shell environment, you may see the following type of error when you try to connect to a repository:

bear-software-abc $ git pull
fatal: Failed to decrypt file '/rds/homes/t/testt/.password-store/git/https/gitlab.bham.ac.uk/testt.gpg' with gpg. exit=2, out=, err=gpg: encrypted with 2048-b
it RSA key, ID 8XGAF3IKDD59A5IJ8CU0T8SPRYAWP5FWZHEAL7HL, created 2025-01-01
    "Taylor Test <t.t.test@bham.ac.uk>"
gpg: public key decryption failed: Inappropriate ioctl for device # (1)!
gpg: decryption failed: No secret key

The precise wording of the error message may vary.

If this happens then please run the following command to ensure that gpg is configured to use the correct terminal interface:

export GPG_TTY=$(tty)

Checking or removing your Personal Access Token¶

Using an expired or revoked PAT

If you try to use an expired or revoked PAT with git, the credential manager responds with an error message and then deletes the stored token. You can then re-run a git command to be prompted to enter a new PAT, following the process as if you were connecting for the first time.

You can verify that your PAT is stored correctly by executing the following command, which will prompt you for your GPG passphrase:

pass show git/https/gitlab.bham.ac.uk/${USER} # (1)!

Replace ${USER} with your University of Birmingham username in lowercase, if required.

If you need to remove your PAT, for example if it has expired or been compromised, you can do so by executing:

pass rm git/https/gitlab.bham.ac.uk/${USER} # (1)!

Replace ${USER} with your University of Birmingham username in lowercase, if required.

N.B. this command prompts for confirmation before deleting the stored token.