Fork me on GitHub

GitHub SSO

How To Use Teleport: Using GitHub for Single Sign On (SSO)

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.


Verify that your Teleport client is connected:

$ tctl status

# Cluster
# 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
$ tctl status

For cloud, login with a teleport user with editor privileges:

tsh logs you in and receives short-lived certificates

tsh login [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
  # connector name that will be used with `tsh --auth=github login`
  name: github
  # 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
    - organization: octocats # Github organization name
      team: admins # Github team name within that organization
      # maps octocats/admins to teleport role access
        - 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
    type: github

Create a file cap.yaml:

kind: cluster_auth_preference
  name: cluster-auth-preference
  type: github
    rp_id: ''
version: v2

Create a resource:

tctl create -f cap.yaml

You can now login with Teleport using github SSO.

Have a suggestion or can’t find something?