Teleport

GitHub SSO

Improve

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

Length: 08:39

This guide explains how to set up Github SSO with Open Source, Enterprise Teleport, self-hosted or cloud.

Prerequisites

Installed Teleport or Teleport Cloud >= 7.1.2
Tctl admin tool >= 7.1.2

Verify that your Teleport client is connected:

$ tctl status

# Cluster  tele.example.com
# Version  7.1.2
# CA pin   sha256:sha-hash-here

Connecting to the cloud

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

Note

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

Tip

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

You can now login with Teleport using github SSO.

Have a suggestion or can’t find something?

IMPROVE THE DOCS