Teleport

Using Teleport's Certificate Authority with GitHub

OpenSource
Enterprise
Cloud

Teleport supports exporting user SSH certificates with configurable key extensions. This allows the Teleport CA to be used in conjunction with GitHub's support for SSH Certificate Authorities. This way, users can access their organizations' repositories with short-lived, signed SSH certificates.

Prerequisites

A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
The tctl admin tool and tsh client tool version >= 13.0.3.
```
tctl version
Teleport v13.0.3 go1.20
tsh version
Teleport v13.0.3 go1.20
```
See Installation for details.

A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 13.0.3, which you can download by visiting your Teleport account.
```
tctl version
Teleport Enterprise v13.0.3 go1.20
tsh version
Teleport v13.0.3 go1.20
```

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

Access to GitHub Enterprise and permissions to modify GitHub's SSH Certificate Authorities.
Make sure you can connect to Teleport. Log in to your cluster using tsh, then use tctl remotely:
```
tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  13.0.3
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
You can run subsequent tctl commands in this guide on your local machine.
For full privileges, you can also run tctl commands on your Auth Service host.

Step 1/3. Import the Teleport CA into GitHub

In order to export the Teleport CA, execute the following command, assigning proxy to the address of your Teleport Proxy Service:

curl 'https://proxy/webapi/auth/export?type=user' | sed 's/^cert-authority //g'

Next, follow the instructions in the guide below to import your Teleport CA into GitHub:

Managing your organization's SSH certificate authorities

The contents of the exported teleport.ca file should by pasted into the "Key" field after clicking "New CA".

Step 2/3. Configure the GitHub key extension

Create or update a role to include the cert_extensions option. The value of name must be [email protected].

kind: role
version: v5
metadata:
  name: developer
spec:
  options:
     cert_extensions:
       - type: ssh
         mode: extension
         name: [email protected] # required to be `[email protected]`.
         value: "{{ external.logins }}"

Assign the developer role to your Teleport user by running the following commands, depending on whether you authenticate as a local Teleport user or via the github, saml, or oidc authentication connectors:

Retrieve your local user's configuration resource:

tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml

Edit out.yaml, adding developer to the list of existing roles:

  roles:
   - access
   - auditor
   - editor
+  - developer

Apply your changes:

tctl create -f out.yaml

Retrieve your github configuration resource:

tctl get github/github --with-secrets > github.yaml

Edit github.yaml, adding developer to the teams_to_roles section. The team you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest team possible within your organization. This team must also include your user.

Here is an example:

  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - developer

Apply your changes:

tctl create -f github.yaml

Warning

Note the --with-secrets flag in the tctl get command. This adds the value of spec.signing_key_pair.private_key to github.yaml. This is a sensitive value, so take precautions when creating this file and remove it after updating the resource.

Retrieve your saml configuration resource:

tctl get --with-secrets saml/mysaml > saml.yaml

Edit saml.yaml, adding developer to the attributes_to_roles section. The attribute you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest group possible within your organization. This group must also include your user.

Here is an example:

  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - developer

Apply your changes:

tctl create -f saml.yaml

Warning

Note the --with-secrets flag in the tctl get command. This adds the value of spec.signing_key_pair.private_key to saml.yaml. This is a sensitive value, so take precautions when creating this file and remove it after updating the resource.

Retrieve your oidc configuration resource:

tctl get oidc/myoidc --with-secrets > oidc.yaml

Edit oidc.yaml, adding developer to the claims_to_roles section. The claim you will map to this role will depend on how you have designed your organization's RBAC, but it should be the smallest group possible within your organization. This group must also include your user.

Here is an example:

  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - developer

Apply your changes:

tctl create -f oidc.yaml

Warning

Note the --with-secrets flag in the tctl get command. This adds the value of spec.signing_key_pair.private_key to oidc.yaml. This is a sensitive value, so take precautions when creating this file and remove it after updating the resource.

Log out of your Teleport cluster and log in again to assume the new role.

Step 3/3. Issue a user certificate

A user certificate may be issued with the following command, where <USERNAME> is the Teleport user to generate the SSH certificate for:

tctl auth sign --out out.cer --user=<USERNAME>

To test that authentication with this signed certificate is working correctly, SSH into github.com with your organization's user:

ssh -i out.cer org-<ID>@github.com

If authentication is successful, a "You've successfully authenticated" message should be displayed in the terminal.

This newly generated certificate may then be used when interacting with GitHub over SSH by adding the following to the ~/.ssh/config file:

Host github.com
 HostName github.com
 IdentityFile path/to/out.cer

When using SSH Certificate Authorities, you should retrieve your GitHub repository's SSH URL from the GitHub UI so the correct SSH user is used for authentication. For more information, see About SSH URLs with SSH certificates.

Have a suggestion or can’t find something?

IMPROVE THE DOCS