Secure and safe login and commits with GitLab + Yubico

We live in a time where data breaches and phishing attacks make daily headlines. These breaches can cause harm to an organization, such as regulatory fines, business downtime, or even worse, reputational damage. In terms of authentication, passwords have been the backbone of online security for decades, however, they're increasingly proving inadequate against sophisticated cyber threats.

GitLab and Yubico have partnered to strengthen software development security through robust authentication measures. Yubico is the inventor of the YubiKey, a hardware security key that delivers phishing-resistant multi-factor authentication (MFA). By implementing FIDO Universal 2nd Factor (U2F) and YubiKey hardware protection, GitLab offers developers a powerful defense against phishing attacks and other cyber threats, ensuring their code and projects remain secure. This collaboration expands enterprise-grade authentication in the GitLab platform, allowing programmers to focus on creating software while maintaining confidence in their account's integrity.

This article explains how to configure GitLab to use YubiKeys to protect developers from online threats. You’ll also learn how to further prevent tampering with GitLab verified commits.

How YubiKeys work

At their core, YubiKeys function as cryptographic hardware tokens that generate and store private keys in a secure element. These keys implement FIDO2/WebAuthn authentication protocols, which can be used as an additional factor to login to GitLab.

Here's how it works when logging in:

1. You enter your username and password.
2. GitLab sends a cryptographic challenge to your browser.
3. Your browser requests the YubiKey to sign this challenge.
4. You physically touch the YubiKey to approve.
5. The YubiKey creates a unique cryptographic signature for that specific service and challenge.
6. GitLab verifies the signature using your public key stored during setup.

Most major security breaches involve compromised passwords. Adding a YubiKey secures your account from a remote breach, even if your password is stolen, so you can rest assured that your GitLab account is secure. Additional key security benefits of using YubiKey for authentication with GitLab include:

• Phishing protection: Fake sites won't have the correct cryptographic keys to verify the response.
• No secrets to steal: The private key never leaves the YubiKey.
• Physical security: Physical presence is required to use it (you must touch the YubiKey).

Setting up YubiKey multifactor authentication in GitLab

Now let’s go over how to set up a Yubikey for multifactor authentication in GitLab. Make sure you're using a supported browser and operating system as they have better WebAuthn support for hardware security keys.

1. First, log in to your GitLab account and go to your user settings (click your avatar in the top left corner and select Preferences).

2. In the left sidebar, click on Account and navigate to the Two-factor Authentication section.

3. If you haven't already enabled 2FA, you'll need to do that first.

   a. Click Enable two-factor authentication.

   b. Scan the QR code with your authenticator app.

   c. Enter the code from your authenticator app.

   d. Enter your GitLab password. If you ever need to access your GitLab account without using Google authentication, you may need to:

   • Use the Forgot password option on the GitLab login page to set up a separate GitLab password.
   • Contact your GitLab administrator to help you set up alternative login methods.

   e. Save your recovery codes in a safe place.

4. Once 2FA is enabled, go back to the previous screen by pressing Manage two-factor authentication and scroll down to the Register hardware token section.

5. Press the Set up new device button.
   a. A popup from your browser should appear. Note: This image may look different depending on your browser. You may also get popups from password managers feel free to ignore them.

    b. Select Use a phone, tablet, or security key.

6. A new popup will appear.

    a. Insert your YubiKey into your computer's USB port.

    b. Touch the metal contact/button on your YubiKey when prompted. The field will automatically fill with a one-time code.

7. Enter your GitLab Password and provide a name for your Hardware Key.
8. Click Register to add the YubiKey to your account.

Congratulations, your YubiKey is now registered and can be used as a second factor when logging into GitLab! You can register multiple YubiKeys to your account for backup purposes. Note: The process may vary slightly among browsers.

YubiKey registered successfully

Signing in with a YubiKey

Now that we have our YubiKey configured, we can log in as follows:

1. Go to GitLab.com.

2. Provide your username and password and then press the Sign in button.
3. You will be sent to the following screen.

    a. A popup, like the one below, should come up. Note: This image may look different depending on your browser. You may also get popups from password managers; feel free to ignore them.

    b. Insert your YubiKey into your computer's USB port.

    c. Touch the metal contact/button on your YubiKey when prompted. The field will automatically fill with a one-time code.

Now, you should be logged in and taken to your GitLab page. Note: The process may vary slightly among browsers.

What happens if I lose my YubiKey?

Yubico recommends that you use and keep a backup YubiKey. When considering your home, car, or office, you wouldn’t think twice about having a backup key to keep in a safe place. Your digital self should get the same level of consideration. A backup YubiKey kept in a safe place provides a quick and safe backup if your primary YubiKey is lost. Keeping a backup will also easily enable you to deactivate the lost YubiKey and add a new primary or secondary YubiKey.

If you do not have an additional YubiKey added, it is recommended to have another form of 2FA added to your accounts. In either case, you should be able to get access to your account and remove the lost key from the account. Please note that if a spare key or another authentication method hasn’t been added, you will need to contact the service/website for help with recovering your account.

GitLab verified commits

To further prevent tampering, you can also configure verified commits. Verified commits in GitLab use GPG (GNU Privacy Guard) signatures to prove that a commit actually came from you. This adds another layer of security on top of authentication by ensuring that not only is your account secure, but every code change can be cryptographically verified as coming from you.

Your YubiKey can store GPG keys:

• The private key is stored securely on the YubiKey.
• The public key is shared with GitLab.
• The key pair is used to sign your commits.

Once the GPG keys have been set up:

• When you make a commit, Git uses your private key to create a signature.
• The GPG key is accessed from the attached YubiKey.
• The signature is stored with the commit metadata.
• GitLab verifies the signature using your public key.

Setting up verified commits

Let’s go over how to configure verified commits. In this example, the GPG key will live inside your YubiKey, providing an extra layer of security.

1. Install required software.

# On macOS
brew install --cask yubico-yubikey-manager
brew install gnupg gpg yubikey-manager

# On Ubuntu/Debian
sudo apt install gnupg gpg yubikey-personalization

# On Windows
# Download and install Gpg4win from https://gpg4win.org

2. Check YubiKey GPG status.

gpg --card-status

3. Generate GPG keys directly on YubiKey (more secure).

# Start GPG edit mode
gpg --card-edit

# Enter admin mode
admin

# Generate key directly on card
# PIN = '123456' | Admin PIN = '12345678'
generate

# Follow prompts
# See documentation for more info 
# https://support.yubico.com/hc/en-us/articles/360013790259-Using-Your-YubiKey-with-OpenPGP

4. Export your public key.

# Get your key ID
gpg --list-secret-keys --keyid-format LONG

# Export the public key
gpg --armor --export YOUR_KEY_ID

5. Add the public key to GitLab.

   a. Click on your GitLab Avatar and select Preferences.

   b. On the side tab select GPG Keys.

   c. Click Add new key.

   d. Paste your public key.

   e. Click Add key.

6. Configure Git.

# Set signing key
git config --global user.signingkey YOUR_KEY_ID

# Enable automatic signing
git config --global commit.gpgsign true

# Tell GPG which key to use
echo "default-key YOUR_KEY_ID" >> ~/.gnupg/gpg.conf

7. Now let’s test the configuration by creating a test commit in a project:

# Make a change in the project
# Add changes
git add .

# Make a test commit
git commit -S -m "Test signed commit"

# Verify signature
git verify-commit HEAD

# Push the change
git push

The git verify-commit HEAD command should show the GPG key used:

gpg: Signature made Wed Feb 26 11:45:00 2025 CST
gpg:                using RSA key YOUR_KEY_ID
gpg: Good signature from “NAME (DESCRIPTION) <EMAIL>" [ultimate]

Then, when viewing the commit in GitLab, you should now see that the commit is verified as follows:

Commit verified with GPG key

You can also use the commits API to check a commit’s signature allowing you to further operationalize the verification workflow.

Learn more

To learn more about GitLab, Yubico, and the solutions each provides, check out these resources:

• Why GitLab
• Why Yubico
• GitLab Security and Compliance Solutions
• GitLab listing in the "Works with YubiKey" catalog
• Verified Commits - GitLab documentation
• Push Rules in GitLab
• Sign Commit with GPG Keys documentation