Teleport

Using Teleport's Certificate Authority with GitHub

Available for:
OpenSource
Team
Cloud
Enterprise

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 the Getting Started guide.
The tctl admin tool and tsh client tool version >= 14.2.0.

See Installation for details.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport v14.2.0 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.2.0 go1.21
Proxy version: 14.2.0Proxy: teleport.example.com

A Teleport Team account. If you don't have an account, sign up to begin your free trial.
The Enterprise tctl admin tool and tsh client tool, version >= 14.1.3.

You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com

A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
The Enterprise tctl admin tool and tsh client tool version >= 14.2.0.

You can download these tools by visiting your Teleport account workspace.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.2.0 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.2.0 go1.21
Proxy version: 14.2.0Proxy: teleport.example.com

A Teleport Enterprise Cloud account. If you don't have an account, sign up to begin a free trial of Teleport Team and upgrade to Teleport Enterprise Cloud.
The Enterprise tctl admin tool and tsh client tool version >= 14.1.3.

You can download these tools from the Cloud Downloads page.

To check version information, run the tctl version and tsh version commands. For example:

tctl version
Teleport Enterprise v14.1.3 git:api/14.0.0-gd1e081e go1.21
  tsh version
Teleport v14.1.3 go1.21
Proxy version: 14.1.3Proxy: teleport.example.com

Access to GitHub Enterprise and permissions to modify GitHub's SSH Certificate Authorities.
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. tctl is supported on macOS and Linux machines. For example:
```
tsh login --proxy=teleport.example.com --user=[email protected]
tctl status
Cluster  teleport.example.com
Version  14.2.0
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.

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 appropriate commands for your authentication provider:

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
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Retrieve your github authentication connector:
```
tctl get github/github --with-secrets > github.yaml
```
Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the github.yaml file. Because this key contains a sensitive value, you should remove the github.yaml file immediately after updating the resource.
Edit github.yaml, adding developer to the teams_to_roles section.

The team you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the team must include your user account and should be the smallest team possible within your organization.

Here is an example:
```
  teams_to_roles:
    - organization: octocats
      team: admins
      roles:
        - access
+       - developer
```
Apply your changes:
```
tctl create -f github.yaml
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Retrieve your saml configuration resource:
```
tctl get --with-secrets saml/mysaml > saml.yaml
```
Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the saml.yaml file. Because this key contains a sensitive value, you should remove the saml.yaml file immediately after updating the resource.
Edit saml.yaml, adding developer to the attributes_to_roles section.

The attribute you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

Here is an example:
```
  attributes_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - developer
```
Apply your changes:
```
tctl create -f saml.yaml
```
Sign out of the Teleport cluster and sign in again to assume the new role.

Retrieve your oidc configuration resource:
```
tctl get oidc/myoidc --with-secrets > oidc.yaml
```
Note that the --with-secrets flag adds the value of spec.signing_key_pair.private_key to the oidc.yaml file. Because this key contains a sensitive value, you should remove the oidc.yaml file immediately after updating the resource.
Edit oidc.yaml, adding developer to the claims_to_roles section.

The claim you should map to this role depends on how you have designed your organization's role-based access controls (RBAC). However, the group must include your user account and should be the smallest group possible within your organization.

Here is an example:
```
  claims_to_roles:
    - name: "groups"
      value: "my-group"
      roles:
        - access
+       - developer
```
Apply your changes:
```
tctl create -f oidc.yaml
```
Sign out of the Teleport cluster and sign 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.