Overview

This article is a follow-up to the secure web access to GitLab cookbook which described how to replace your VPN and implement zero trust security for browser-based (HTTPS) access to your self-managed GitLab instance.

For Git operations that are not browser-based - such as programmatic access, Command Line Interface (CLI) tools, Graphical User Interface (GUI) applications, etc - GitLab doesn't use standard web-based username and password authentication. Instead, it uses 2 other protocols and authentication schemes:

• Secure Shell (SSH) Key authentication
• Project/Personal Access Tokens (PAT) authentication

All major managed Git providers - GitLab, GitHub, BitBucket - have announced the deprecation of the use of account passwords for Git operations. You can still support users performing Git operations using account passwords - follow the instructions below for PAT authentication.

This cookbook shows you how to use Banyan to support SSH and PAT protocols/authentication schemes seamlessly, while still ensuring zero trust security.

Approach

For a high-level architecture diagram, review the approach section in the secure web access to GitLab solution guide.

For Git operations, we use Banyan's infrastructure service capabilities with short-lived X509 certificates. We will define 2 additional services for each auth mechanism and protocol that GitLab supports:

• SSH Service for SSH Keys, that use the SSH protocol on backend port 22
• TCP Service for Access Tokens and Passwords, that use the HTTP/HTTPS protocol on backend port 80/443

The diagram below depicts the traffic flow for each service:

The table summarizes the Banyan services and functionality used:

In this cookbook, the end-user domain for our self-managed GitLab is gitlab.medsoft.digital, and the backend domain is of the form gitlab.c.banyan-test-drive.internal. The traffic routing will look as follows:

Prerequisites

Before you get started, ensure you have done the following:

1. Go through the secure access to GitLab cookbook and publish a GitLab web service
2. Register a wildcard domain that you will use to publish various SSH services; a common pattern we recommend is a ssh sub-domain, such as: *.ssh.medsoft.digital
3. Configure your GitLab user for SSH Key authentication and/or PAT authentication

Steps

Now, let’s dive into how you can support SSH and PAT protocols/authentication for GitLab with Banyan in four easy steps:

1. Define an SSH service to enable GitLab SSH Key authentication
2. Connect via the Banyan App and perform Git operations using SSH
3. Define a Generic TCP service to enable GitLab PAT authentication
4. Connect via the Banyan App and perform Git operations using HTTPS

Step 1. Define an SSH service to enable GitLab SSH Key authentication #

1.1 Register an SSH service for GitLab. Navigate to Manage Services > Infrastructure > Register New Service.

1.2 Select SSH Service.

1.3 Enter a Service Name, Description, and select an icon.

1.4 Configure the Service Attributes:

• Select the connector you'll be using.
• Set a Service Domain Name following your convention for SSH services
• Set How should incoming connections be proxied? to Fixed Backend Domain
• Enter the private IP address or domain name of your Self-Managed GitLab as your Backend Domain.
• Set the Backend Port to 22 for SSH

1.5 Under SSH Desktop App Settings, configure how the App should manage SSH configs

• Set the SSH Host Directive to your self-managed GitLab's user-facing domain name

1.6 Select a basic policy: AllUsersAndDevices-Infra

1.7 Once completed, select Save.

1.8 Test your connection. Ensure that the tests all have green checks under Status.

Step 2. Connect via the Banyan App and perform Git operations using SSH

2.1 In GitLab, ensure your user account is configured for SSH Key authentication

2.2 Navigate to your repository in GitLab and take note of your repo's SSH address

2.3 Open up the Banyan App and click connect on the gitlab-ssh service

2.4 Now, you can perform Git operations on your repo using SSH

In our example, the repo can be cloned via:

git clone git@gitlab.medsoft.digital:bob/my-awesome-project.git

Behind the scenes, the Banyan app has updated your SSH config file to use the local TLS proxy and short-lived certificates. You can check your SSH configs:

$ cat ~/.ssh/banyan.config
Host gitlab.medsoft.digital # gitlab.ssh.medsoft.digital 8443 gitlab-ssh.global-edge.bnn
Hostname gitlab.ssh.medsoft.digital
ProxyCommand "C:\Program Files\Banyan\resources\bin\banyanproxy.exe" %h 8443

Step 3. Define a Generic TCP service to enable GitLab PAT authentication #

3.1 Register an Generic TCP service for GitLab. Navigate to Manage Services > Infrastructure > Register New Service.

3.2 Select TCP Service.

3.3 Enter a Service Name, Description, and select an icon.

3.4 Configure the Service Attributes:

• Select the connector you'll be using.
• Set the Service Domain Name to be your self-managed GitLab's user-facing domain name from the secure web access to GitLab cookbook
• Set the Backend DNS Override for Service Domain Name to be the private IP address or domain name of your Self-Managed GitLab

3.5 Under Service Connection Settings, configure how the App should manage TCP connectivity

• Set the Assigned Listen Port to a standard number in the user range (1024-49151)

3.7 Select a basic policy: AllUsersAndDevices-Infra

3.8 Once completed, select Save.

Step 4. Connect via the Banyan App and perform Git operations using HTTPS

4.1 In GitLab, ensure your user account is configured for PAT authentication or Password authentication

4.2 Navigate to your repository in GitLab and take note of your repo's HTTPS address

4.3 Open up the Banyan App and click connect on the gitlab-pat service

Now, a local forwarding proxy is running on the port specified. Add a global http.proxy config setting so Git clients know to use the local proxy for your self-managed GitLab.

In our example, the self-managed GitLab is at gitlab.medsoft.digital, so the config line we add looks as below. You should replace https://gitlab.medsoft.digital and the local port with the specifics for your setup.

git config --global 'http.https://gitlab.medsoft.digital/.proxy' http://localhost:9143

4.4 Now, you can perform Git operations on your repo over HTTPS

In our example, the repo can be cloned via:

git clone https://gitlab.medsoft.digital/bob/my-awesome-project.git

4.5 You can extend the HTTP Connect Proxy technique to interact with the GitLab API over HTTPS

Set the https_proxy environment variable to let clients interacting with the GitLab API know that they should use the local forwarding proxy to establish connectivity.

export https_proxy=http://localhost:9143

Some clients provide a dedicated command to specify a forwarding proxy. For example, curl provides --proxy flag, so you can do:

curl --proxy "http://localhost:9143" --header "Authorization: Bearer $PAT" https://gitlab.medsoft.digital/api/v4/projects

Notes

1. If you're using a self-signed certificates on the GitLab backend, you have to tell GitLab clients to disable TLS verification.

To your global gitconfig, add an sslVerify=false line, like:

[http "https://gitlab.medsoft.digital/"]
        proxy = http://localhost:9143
        sslVerify = false

For curl, set the --insecure flag, like:

curl --insecure --proxy "http://localhost:9143" --header "Authorization: Bearer $PAT" https://gitlab.medsoft.digital/api/v4/projects

2. You can bundle all the GitLab services as well as your other DevOps tools that you need to manage. These will show up together in the Banyan App, for convenient end user access.