How To Use Teleport: Using GitHub for Single Sign On (SSO)
Length: 09:52
This guide explains how to set up Github SSO with Open Source, Enterprise Teleport, self-hosted or cloud.
Prerequisites
- Installed Teleport or Teleport Cloud >= 8.0.7
- Tctl admin tool >= 8.0.7
Verify that your Teleport client is connected:
$ tctl status
# Cluster tele.example.com
# Version 8.0.7
# CA pin sha256:sha-hash-here
To try this flow in the cloud, login into your cluster using tsh, then use tctl remotely:
$ tsh login --proxy=myinstance.teleport.sh
$ tctl status
For cloud, login with a teleport user with editor privileges:
tsh logs you in and receives short-lived certificates
tsh login --proxy=myinstance.teleport.sh [email protected]try out the connection
tctl get nodes
Step 1/2. Create Github connector
Define a Github connector:
# Create a file called github.yaml:
kind: github
version: v3
metadata:
# connector name that will be used with `tsh --auth=github login`
name: github
spec:
# Client ID of Github OAuth app
client_id: <client-id>
# Client secret of Github OAuth app
client_secret: <client-secret>
# Connector display name that will be shown on web UI login screen
display: Github
# Callback URL that will be called after successful authentication
redirect_url: https://<proxy-address>/v1/webapi/github/callback
# Mapping of org/team memberships onto allowed logins and roles
teams_to_logins:
- organization: octocats # Github organization name
team: admins # Github team name within that organization
# maps octocats/admins to teleport role access
logins:
- access
To obtain a client ID and client secret, please follow Github documentation on how to create and register an OAuth app.
Be sure to set the "Authorization callback URL" to the same value as redirect_url in the resource spec.
Teleport will request only the read:org OAuth scope, you can read more about
Github OAuth scopes.
Finally, create the connector using tctl
resource management command:
tctl create github.yaml
When going through the Github authentication flow for the first time, the application must be granted access to all organizations that are present in the "teams to logins" mapping, otherwise Teleport will not be able to determine team memberships for these orgs.
Step 2/2. Configure authentication preference
Configure Teleport Auth Service Github for authentication:
# Snippet from /etc/teleport.yaml
auth_service:
authentication:
type: github
Create a file cap.yaml:
kind: cluster_auth_preference
metadata:
name: cluster-auth-preference
spec:
type: github
webauthn:
rp_id: 'example.teleport.sh'
version: v2
Create a resource:
tctl create -f cap.yaml
You can now login with Teleport using github SSO.