Set up Single Sign-On with GitHub

This guide explains how to set up GitHub Single Sign On (SSO) so you can automatically map teams in your GitHub organization to users and roles in Teleport.

Prerequisites

• A GitHub organization with at least one team.
• Teleport role with access to maintaining github resources for using tctl from the Desktop. This is available in the default editor role.

tsh login --proxy=teleport.example.com [email protected]
tctl status
Cluster  teleport.example.com
Version  9.3.7
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status
Cluster  myinstance.teleport.sh
Version  9.3.8
CA pin   sha256:sha-hash-here

Step 1/3. Create a GitHub OAuth app

Create and register a GitHub OAuth App. When you do so, ensure that your OAuth App's "Authentication callback URL" is the following:

https://PROXY_ADDRESS/v1/webapi/github/

PROXY_ADDRESS must be the public address of the Teleport Proxy Service.

Instructions for creating a GitHub OAuth app are available here:

Creating an OAuth App

Step 2/3. Create a GitHub authentication connector

Define a GitHub authentication connector by creating a file called github.yaml with the following content:

kind: github
version: v3
metadata:
  # Connector name that will be used with `tsh --auth=github login`
  name: github
spec:
  # Client ID of your GitHub OAuth App
  client_id: <client-id>
  # Client secret of your GitHub OAuth App
  client_secret: <client-secret>
  # Connector display name that will be shown on the 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 the "access" Teleport role
      logins:
        - access

The values of client_id, client_secret, and redirect_url come from the GitHub OAuth App you created earlier.

Teleport will request only the read:org OAuth scope. Read more about OAuth scopes in GitHub's documentation:

GitHub OAuth scopes

Finally, create the connector using tctl:

tctl create github.yaml
authentication connector "github" has been created

Step 3/3. Configure authentication preference

Configure the Teleport Auth Service to enable the GitHub authentication connector.

Obtain your existing cluster_auth_preference resource:

tctl get cap > cap.yaml

If you have not defined a cluster_auth_preference, cap.yaml will be blank.

Ensure that cap.yaml includes the following content:

kind: cluster_auth_preference
metadata:
  name: cluster-auth-preference
spec:
  type: github
  webauthn:
    rp_id: 'example.teleport.sh'
version: v2

For rp_id, use the public address of your Teleport Proxy Service.

Create the resource:

tctl create -f cap.yaml
cluster auth preference has been updated

# Snippet from /etc/teleport.yaml
auth_service:
  authentication:
    type: github

You can now log in with Teleport using GitHub SSO.

Run the following to log out of Teleport and log in again using GitHub SSO.

tsh logout
Logged out all users from all proxies.
tsh login --proxy=tele.example.com

When you sign in for the first time, you will see a prompt to authorize your GitHub OAuth app:

After logging in successfully, you will see the following:

Troubleshooting

Using the Web UI

If you get "access denied" or other login errors, the number one place to check is the Audit Log. You can access it in the Activity tab of the Teleport Web UI.

Example of a user being denied because the role clusteradmin wasn't set up:

{
  "code": "T1001W",
  "error": "role clusteradmin is not found",
  "event": "user.login",
  "method": "oidc",
  "success": false,
  "time": "2019-06-15T19:38:07Z",
  "uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"
}

Teleport does not show the expected Nodes

When Teleport's Auth Service receives a request to list Teleport Nodes, it only returns the Nodes that a user is authorized to access.

A user's Teleport roles must grant the user explicit access to Nodes with a particular label before the user can view those Nodes. The Auth Service compares the user's traits.logins with the allow and deny rules defined in each of the user's roles.

If the user's logins match a role's allow and deny rules, and a Node's labels match the keys and values listed within a role's node_labels field, then the Auth Service will list the Node in response to the user's request.

When configuring SSO, ensure that the identity provider is populating each user's traits correctly. For a user to see a Node in Teleport, the result of populating a template variable in a role's allow.logins must match at least one of a user's traits.logins.

In this example a user will have usernames ubuntu, debian and usernames from the SSO trait logins for Nodes that have a env: dev label. If the SSO trait username is bob then the usernames would include ubuntu, debian, and bob.

kind: role
metadata:
  name: example-role
spec:
  allow:
    logins: ['{{external.logins}}', ubuntu, debian]
    node_labels:
      'env': 'dev'
version: v5