Skip to content

Improve the security guarantees of using Echoes HQ together with GitLab by proxying the GitLab API

License

Notifications You must be signed in to change notification settings

EchoesHQ/gitlab-proxy

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

38 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

gitlab-proxy

Improve the security guarantees of using Echoes HQ together with GitLab by proxying the GitLab API. The proxy serves two main purposes:

  • Restrict the set of exposed API endpoints to the subset necessary for Echoes HQ to operate.
  • Provide its own authentication mechanism so that you don't have to trust Echoes HQ with your GitLab token.

See Echoes documentation for more information.

Quickstart

Step 1: Clone the repository

git clone [email protected]:EchoesHQ/gitlab-proxy.git

Step 2: Build the Docker image

Navigate to the nginx-proxy folder:

$ cd nginx-proxy

Build the image:

$ docker build . -t gitlab-proxy

Step 3: Create the environment file

Copy the .env.example file:

$ cp .env.example .env

The default configuration targets gitlab.com, but can be overriden to the URL of your choice using the GITLAB_URL variable. For example: GITLAB_URL=https://gitlab.mycompany.com.

Step 4: Set the API keys

Copy the api_keys.conf.example into a mount location on the host, for instance:

$ cp api_keys.conf.example /tmp/api_keys.conf

Set the API keys in api_keys.conf:

  • Generate an API key to be given to Echoes during the GitLab integration installation
$ openssl rand -base64 18
oLAVcK2LAzfMpYXT10ymK1qL

The final content should resemble the following:

map $http_PRIVATE_TOKEN $gitlab_token {
    default "";

    "oLAVcK2LAzfMpYXT10ymK1qL" "glpat-fake-token";
}

Step 5: Run the proxy

The proxy expects the file api_keys.conf to be mounted to /etc/nginx/api_keys.

The following command runs the proxy on port 8080:

docker run \
    --env-file .env \
    -v /tmp/api_keys.conf:/etc/nginx/api_keys/api_keys.conf:ro \
    -p 8080:80 gitlab-proxy

Step 6: Test the setup

Set the HTTP Header PRIVATE-TOKEN to the API key set in the api_keys.conf file earlier, e,g oLAVcK2LAzfMpYXT10ymK1qL:

curl --location --request GET 'http://0.0.0.0:8080/api/v4/groups/<REPLACE_ME>/members' \
    --header 'Content-Type: application/json' \
    --header 'PRIVATE-TOKEN: oLAVcK2LAzfMpYXT10ymK1qL'

Step 7: Configure a GitLab integration within Echoes

Follow the GitLab integration documentation to setup a new integration pointing to your self-hosted GitLab API proxy, using the API key generated in step 4 as your personal access token.

Configuration with an upstream directive (Optional)

An upstream configuration may be necessary for on-premises GitLab instances. The following steps describe how to use an upstream configuration with the proxy.

Step 1: Copy the api_backends.conf file

Copy the api_backends.conf file containing an example of upstream into a mount location on the host:

$ cp api_backends.conf /tmp/api_backends.conf

Step 2: Configure the upstream

Modify the copied api_backends.conf file in order to map the gitlab instance IP(s) of your choice.

Step 3: Set the GITLAB_URL environment variable

Set the environment variable GITLAB_URL from the .env file as follow: <protocol><upstream_name> e,g http://example:

GITLAB_URL=http://example

Step 4: Run the proxy

The proxy expects the file api_backends.conf to be mounted to /etc/nginx/api_backends/api_backends.conf:

docker run \
    --env-file .env \
    -v /tmp/api_keys.conf:/etc/nginx/api_keys/api_keys.conf:ro \
    -v /tmp/api_backends.conf:/etc/nginx/api_backends/api_backends.conf:ro \
    -p 8080:80 gitlab-proxy

Restricted access

The proxy is preconfigured to only accept connections from Echoes IP addresses.

# gitlab-proxy.conf
include proxy/ip_restriction.conf

If this turns out to be a problem for your particular deployment, this setting can be overriden by mounting another configuration file.

-v /tmp/ip_restriction.conf:/etc/nginx/proxy/ip_restriction.conf:ro

K8s deployment example

An example of k8s deployment is given for information only. A more robust deployment should be managed via Helm, allowing the setup of metrics, ingress probes and other fine aspects of a production ready deployment.

The image used is local, you may want to use your own published custom image:

image: gitlab-proxy
imagePullPolicy: Never

TL;DR

A secret would need to be created:

$ kubectl create secret generic api-keys-secrets --from-file=api-keys.conf=/tmp/api_keys.conf

Refer to Step 4 for more details.

Then mounted as follow:

volumeMounts:
  - name: api-keys
    mountPath: "/etc/nginx/api_keys"
    readOnly: true

The GITLAB_URL environment variable has to be set:

env:
  - name: GITLAB_URL
    value: "https://gitlab.com"

Deploy the proxy:

$ kubectl apply -f deployment.example.yaml

The proxy is reachable on port 8084.

Audit & troubleshooting

API keys

The setting of the API keys is done in the api_keys.conf file. This file should be mounted dynamically and not baked into the docker image.

API routes

Allowed endpoints and methods are defined in gitlab-api-routes folder.

HTTP headers

The proxy always adds the X-Echoes-GitLab-Proxy-Version.

Access logs

Access logs are available for auditing in /var/log/nginx/api_access.log.

About

Improve the security guarantees of using Echoes HQ together with GitLab by proxying the GitLab API

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published