How To Use Teleport: Using GitHub for Single Sign On (SSO)
This guide explains how to set up Github SSO with Open Source, Enterprise Teleport, self-hosted or cloud.
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
$ tsh login --proxy=myinstance.teleport.sh $ tctl status
For cloud, login with a teleport user with editor privileges:
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.
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.
Configure Teleport Auth Service Github for authentication:
# Snippet from /etc/teleport.yaml auth_service: authentication: type: github
Create a file
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