Skip to main content
Version: 18.x (unreleased)

Proxy Git Commands with Teleport for GitHub

Teleport can proxy Git commands and use short-lived SSH certificates to authenticate GitHub organizations.

In this guide, you will:

  • Create a GitHub OAuth application.
  • Configure SSH certificate authorities for your GitHub organizations.
  • Create Teleport resources for the GitHub integration.
  • Run Git commands through Teleport.

How it works​

GitHub enables organizations to configure a list of SSH Certificate Authorities (CAs) for authentication. This feature allows access to the organization's repositories using short-lived SSH certificates signed by an approved CA, such as a Teleport CA. Optionally, organizations can enforce stricter security by requiring these signed SSH certificates for access, effectively disabling the use of personal SSH keys and access tokens.

Teleport users can configure their Git repositories to proxy through Teleport. After setup, Git commands automatically route through Teleport, which impersonates their GitHub identities using short-lived SSH certificates signed by Teleport's CA for authentication with GitHub. Each Git command proxied through Teleport is also logged in Teleport's audit events.

To retrieve a user's GitHub identity, tsh initiates the GitHub OAuth flow by opening a browser window for the user to log in with their GitHub credentials.

Note that Teleport proxies Git commands through SSH but the users should continue to access GitHub through their browsers.

Prerequisites​

  • A running Teleport Enterprise cluster version 17.2 or above. If you want to get started with Teleport, sign up for a free trial.

  • The tctl admin tool and tsh client tool.

    Visit Installation for instructions on downloading tctl and tsh.

  • Access to GitHub Enterprise and permissions to modify GitHub's SSH certificate authorities and configure OAuth applications.
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example: 
    tsh login --proxy=teleport.example.com --user=email@example.com
    tctl status
    Cluster  teleport.example.com
    Version  17.0.0-dev
    CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.
  • Git locally installed

Step 1/4. Configure a GitHub OAuth application​

The GitHub integration requires a GitHub OAuth application to obtain users' GitHub identities. You can skip this step if the Teleport users use GitHub SSO to sign in Teleport.

Go to "OAuth Apps" under "Developer Settings" of your organization's settings. Click on "New OAuth App".

Fill in the details. Use the following for "Authentication callback URL":

https://teleport-proxy-address/v1/webapi/github/

Once the OAuth application is created, create a client secret and remember the client ID and the secret for the next step:

Step 2/4. Create a GitHub integration and export the CAs​

Now create a yaml file that represents the Github integration:

# github_integration.yaml
kind: integration
sub_kind: github
version: v1
metadata:
  name: github-my-github-org
spec:
  github:
    organization: my-github-org
  credentials:
    id_secret:
      id: oauth-app-client-id
      secret: oauth-app-client-secret

Replace my-github-org with the organization name, and replace oauth-app-client-id and oauth-app-client-secret with values from the previous step.

To create the resource with tctl, run:

tctl create -f github_integration.yaml

Once the integration resource is created, export the CA to be used for GitHub:

tctl auth export --type github --integration github-my-github-org

Now go to the "Authentication Security" page of your GitHub organization. Click on "New CA" under the "SSH certificate authorities" section, and copy-paste the CA exported from the above tctl auth export command.

Step 3/4. Configure access​

User access is granted through git_server resources. The git_server references the integration created in the previous step:

# git_server.yaml
kind: git_server
sub_kind: github
version: v2
spec:
  github:
    integration: github-my-github-org
    organization: my-github-org

To create the resource with tctl, run:

tctl create -f git_server.yaml

The user role must have github_permissions configured to allow access to your GitHub organization. For example:

# role_with_github_permissions.yaml
kind: role
metadata:
  name: github-access
spec:
  allow:
    github_permissions:
    - orgs:
      - my-github-org
version: v7

Assign the github-access role to your Teleport user by running the appropriate commands for your authentication provider:

  1. Retrieve your local user's roles as a comma-separated list:

    ROLES=$(tsh status -f json | jq -r '.active.roles | join(",")')

  2. Edit your local user to add the new role:

    tctl users update $(tsh status -f json | jq -r '.active.username') \  --set-roles "${ROLES?},github-access"

  3. Sign out of the Teleport cluster and sign in again to assume the new role.

Step 4/4. Connect​

Use tsh git ls to view a list of GitHub organizations you have access to:

tsh git ls
Type   Organization  Username URL------ ------------- -------- --------------------------------GitHub my-github-org my-user  https://github.com/my-github-org

Teleport requires your GitHub identity to impersonate you. If you haven't provided it yet, run the following command:

tsh git login --github-org my-github-org
  If browser window does not open automatically, open it by clicking on the link:   http://127.0.0.1:55555/some-id  Your GitHub username is my-user.

This command opens a browser, prompting you to authenticate with GitHub via the OAuth app:

To clone a repository from your GitHub organization, find the SSH clone URL and run:

tsh git clone git@github.com:my-github-org/my-repo.git
Cloning into 'my-repo'...

To configure an existing Git repository with Teleport, go to the repository and run:

tsh git config update
The current Git directory is configured with Teleport for GitHub organization "my-github-org".

Once the repo is cloned or configured, you can use git commands as normal:

$ cd my-repo
$ git fetch

Note that the OAuth app authentication flow and Git repository configuration are one-time setups and don't need to be repeated.

Further reading​