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
- The Teleport Auth Service and Proxy Service v11.3.1, either self hosted or deployed on Teleport Cloud.
- The GitHub SSO authentication connector. For more information, see GitHub SSO.
- Access to GitHub Enterprise and permissions to modify GitHub's SSH Certificate Authorities.
Step 1/3. Import the Teleport CA into GitHub
In order to export the Teleport CA, execute the following command:
Log in to your cluster with tsh so you can use tctl from your local machine.
You can also run tctl on your Auth Service host without running "tsh login"
first.
tsh login --proxy=teleport.example.com --user=myusertctl 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 > 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
Retrieve your saml
configuration resource:
tctl get 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
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc > 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 saml.yaml
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.