Using SSH keys to connect to GitLab from a Windows client

For those who have not used GitLab before, it is an open-source code repository and collaboration tool (similar to GitHub). Our Linux support team has been using it for several years, and over the past year, we have begun using it for our Windows-based projects and code repositories.

In GitLab, there are 2 authentication methods people can use with their push/pull requests: username & password, or SSH keys. With the username & password option, the user is prompted to enter their credentials for each push/pull request. While functional, this process becomes tedious when pushing up multiple changes to code-based automation systems. The alternative to username/password authentication is using a pair of SSH public/private cryptographic keys. In this process, the public SSH key is uploaded to the user’s profile in GitLab, and the private SSH key is added to the user’s SSH profile on their local computer. When a push/pull request is made, the SSH keys are automatically used by the computer to authenticate to the GitLab server. Since the SSH keys are secured by the user’s local and GitLab profiles, there is little risk of someone else using the keys to impersonate the user (unless the user’s profile is compromised first).

To add SSH cryptographic keys to your authentication process:

  1. Install the Git client for Windows, if it hasn’t already been done. (https://git-scm.com/)
  2. Add the OpenSSH Agent feature to the Windows desktop.
  3. Use ssh-keygen to create a public/private key pair.
  4. Upload the public SSH key to your GitLab profile.
  5. Add the private SSH key path to the local SSH Agent service.
  6. Configure your local Git client to use the OpenSSH Agent service.

Install the OpenSSH Agent (client)

  1. Open PowerShell as an Administrator.
  2. Install the OpenSSH Client.
    • Get-WindowsCapability -Online | Where-Object Name -like 'OpenSSH*'
    • Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0
  3. Start the OpenSSH Client service.
    • Start-Service ssh-agent
  4. Set the OpenSSH Client service to start automatically.
    • Set-Service -Name ssh-agent -StartupType 'Automatic'

Create an SSH cryptographic key pair

  1. Create an SSH key in your profile’s ssh folder.
    • ssh-keygen -t ed25519
    • Filename: C:\Users\<username>/.ssh/id_ed25519
ssh-keygen

Add the Private key to the OpenSSH service

  1. Open PowerShell.
  2. Add the Private to the OpenSSH service.
    • ssh-add c:\Users\<username>\.ssh\id_ed25519
    • Note: If the system returns Could not add identity ” “: communication with agent failed. Use the Service Control executable to add a path for ssh in the registry and then retry the ssh-add command.
      • sc.exe create sshd binPath=C:\Windows\System32\OpenSSH\ssh.exe
  3. Reconfigure Git to use OpenSSH.
    • git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe

Upload Public SSH key to Gitlab

Next, log in to your GitLab repository and add your Public key into your GitLab profile.

  1. Log in to your GitLab repository.
  2. Click on the drop-down menu beside your username.
  3. Select Edit Profile.
  4. On the Profile menu, select SSH Keys.
  5. Copy the text from your public SSH key (c:\Users\<username>/.ssh/id_ed25519.pub) and paste it into the Key textbox. Add a Title that you will recognize as being for the SSH key pair from your computer, set an (optional) expiry date, and click Add key.

Test the SSH keys

Once the SSH keys have been added to the local and remote user profiles, the SSH authentication can be tested using a Git client Push or Pull request.

  1. Open a new Terminal session.
  2. Change the active directory to a local Git repository (c:\scripts\code\prometheus in the example below).
  3. Execute a Push/Pull/Status request.

The Git request will now connect to the server without requesting a username and password.

Secure the Private key

After adding your Private SSH key to the OpenSSH service on your computer, Microsoft strongly recommends storing a copy of it in a secure location and then removing the file from your local computer. This will prevent someone from copying your Private key to another system and impersonating your account. However, if you lose access to your (secured) Private key, a new key pair will have to be generated, and the public key uploaded/replaced on any systems where it has been used.

1 thought on “Using SSH keys to connect to GitLab from a Windows client”

Leave a Reply

Your email address will not be published.