Fork me on GitHub

Teleport

Set up Single Sign-On with GitHub

Improve
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 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. This organization must not have external SSO set up, or Teleport will refuse to create the GitHub authentication connector.
  • Teleport role with access to maintaining github resources for using tctl from the Desktop. This is available in the default editor role.
  • A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.

  • The tctl admin tool and tsh client tool version >= 12.1.1.

    tctl version

    Teleport v12.1.1 go1.19

    tsh version

    Teleport v12.1.1 go1.19

    See Installation for details.

  • A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.

  • The Enterprise tctl admin tool and tsh client tool version >= 12.1.1, which you can download by visiting the customer portal.

    tctl version

    Teleport Enterprise v12.1.1 go1.19

    tsh version

    Teleport v12.1.1 go1.19

Cloud is not available for Teleport v.
Please use the latest version of Teleport Enterprise documentation.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=teleport.example.com [email protected]
tctl status

Cluster teleport.example.com

Version 12.1.1

CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678

You can run subsequent tctl commands in this guide on your local machine.

For full privileges, you can also run tctl commands on your Auth Service host.

To connect to Teleport, log in to your cluster using tsh, then use tctl remotely:

tsh login --proxy=myinstance.teleport.sh [email protected]
tctl status

Cluster myinstance.teleport.sh

Version 12.1.1

CA pin sha256:sha-hash-here

You must run subsequent tctl commands in this guide on your local machine.

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 roles
  teams_to_roles:
    - organization: octocats # GitHub organization name
      team: admins # GitHub team name within that organization
      # Maps octocats/admins to the "access" Teleport role
      roles:
        - access
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
  # URL of your GitHub Enterprise Server instance (if applicable)
  endpoint_url: https://<github-enterprise-server-address>
  # 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 roles
  teams_to_roles:
    - organization: octocats # GitHub organization name
      team: admins # GitHub team name within that organization
      # Maps octocats/admins to the "access" Teleport role
      roles:
        - 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

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 organizations.

After a user authenticates, Teleport will add the user's GitHub username to their internal.logins trait for their Teleport session. The preset access role has this trait variable configured to include the GitHub user as an authorized SSH login. Here is an example role configuration snippet using the trait variable:

  allow:
    # List of allowed SSH logins
    logins: ['{{internal.logins}}', ubuntu, debian]
    # List of node labels that users can SSH into
    node_labels:
      '*': '*'

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

You can also edit your Teleport configuration file to include the following:

# 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

If browser window does not open automatically, open it by clicking on the link:

http://127.0.0.1:56334/6bf976e6-a4be-4898-94eb-8a7b01af2158

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

GitHub SSO authorization view

After logging in successfully, you will see the following:

Login success view

You will receive the details of your user session within the CLI.

> Profile URL: https://tele.example.com:443

Logged in as: jeff

Cluster: tele.example.com

Roles: access

Logins: jeff, ubuntu, debian, -teleport-internal-join

Kubernetes: enabled

Kubernetes users: dev

Kubernetes groups: developer

Valid until: 2023-03-08 17:13:50 -0600 CST [valid for 7h51m0s]

Extensions: permit-port-forwarding, permit-pty, private-key-policy

Troubleshooting

Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator must be able to:

  • Ensure that HTTP/TLS certificates are configured properly for both Teleport proxy and the SSO provider.
  • Be able to see what SAML/OIDC claims and values are getting exported and passed by the SSO provider to Teleport.
  • Be able to see how Teleport maps the received claims to role mappings as defined in the connector.

If something is not working, we recommend to:

  • Double-check the host names, tokens and TCP ports in a connector definition.

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.

Audit Log Entry for SSO Login error

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 (e.g., to display Nodes in the Web UI or via tsh ls), it only returns the Nodes that the current user is authorized to view.

For each Node in the user's Teleport cluster, the Auth Service applies the following checks in order and, if one check fails, hides the Node from the user:

  • None of the user's roles contain a deny rule that matches the Node's labels.
  • At least one of the user's roles contains an allow rule that matches the Node's labels.

If you are not seeing Nodes when expected, make sure that your user's roles include the appropriate allow and deny rules as documented in the Teleport Access Controls Reference.

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