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

Video Length: 08:38


This video walks through how to set up Teleport to use GitHub for Single Sign On. Once you have completed this tutorial, you will be able to:

  • Authenticate with GitHub users into Teleport in Web and CLI
  • Map teams within a GitHub organization to logins and K8s usage within Teleport
  • Configure OAuth settings with GitHub org
  • Configure GitHub auth connector within Teleport
  • Set GitHub as the default auth connector

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

Steven: Welcome to this “How To Use Teleport” video from Gravitational [now Teleport] for how to use GitHub as a single sign-on authenticator with Teleport. Teleport is a simple, secure access solution that developers use to remotely manage their cloud or edge environments through SSH or Kubernetes. Let’s step through how we’re going to configure GitHub for single sign-on with Teleport. We’re going to be matching specific GitHub teams to SSH logins such as “root” users access. We’re going to be matching GitHub teams for the Kubernetes usage, whether matched to groups or users.

Steven: Now, in terms of the example today, we’ll have two teams. First is the “oncall” team that has a monitor SSH login access and the Kubernetes “oncall” Kubernetes group. And we have another “oncalladmins” team that has route access and the Kubernetes group “system:masters”. Now, to use that, we’re going to have two users. One is the “exampleoncall” user, which will only be in the “oncall” team and just has the monitor SSH access. Then the “exampleoncalladmin” is in both teams and then thus has both login access for monitoring route and also is in both the “oncall” community’s group, as well as the “system:masters” group after authenticating.

Authenticate with GitHub users into Teleport in Web and CLI

Steven: Our first step is going to be configuring the GitHub organization for authentication. You’ll want to have an organization configured that has one or more teams with members assigned to those teams based on the type of usage they’ll have. We recommend turning on the two-factor authentication option to provide you added security beyond just passwords.

Configure OAuth settings with GitHub org

Steven: Next, we’ll be configuring the Teleport OAuth application, which is the communication protocol used for security between Teleport and GitHub. You can see here our GitHub organization “AcmeExample” that has two members that will be part of the teams. Here we can go to our settings for organization. We’ll first go to security and turn on the two-factor authentication. Two-factor authentication is not required, but we do recommend it for added security. Next, we’ll go to the OAuth setting for apps. We have to register an application. We’re going to name it Teleport. Next, we’ll provide the homepage URL of our Teleport instance. Next, we’ll be writing a callback URL that is used once the authentication process is executed on GitHub. Now that we’ve completed that, we can register the application. We can see we have a client ID in secret. We’ll want to take note of those values, and we’ll use them in our GitHub YAML file.

Configure GitHub auth connector within Teleport

Steven: Next, you can see the same information we provided when we registered. Now that the GitHub organization has been configured, we can configure within Teleport. We will be configuring the GitHub authentication or auth connector that’ll be within a GitHub YAML file. We’ll be setting that same client ID and client secret, providing the callback URL. We’ll also be setting the logins in Kubernetes, allowed for the specific GitHub teams within that organization. One tip is to make sure to use lowercase team names in the connector, not CamelCase. Lastly, we’ll be adding that auth connector to Teleport via tctl. You can also directly add it via the web as another option. Now, let’s take a look at the yaml file. You can see we’ve set the client ID secret and callback URL. So we’ve mapped the organization and teams to specific login and Kubernetes access. And now that we have our file completed, we can use a tctl command to create it, and it will confirm that it has been created.

Steven: Now that we have the GitHub auth connecter configured, we can set GitHub as the default authentication. You simply edit the teleport.yaml to set the authentication configuration. You also want to make sure that you’re using a signed SSL certificate so that the GitHub can communicate back to the Teleport instance. Once that is done, you’ll simply restart Teleport, and GitHub is now your default authentication mechanism. So we can see what’s in the teleport.yaml file. We’re going to add an option to the auth service. I’m going to say the GitHub authentication. I’m going to list the type as GitHub, and that enforces GitHub as the default authentication. After saving this, just simply restart your Teleport service. Now that we’ve finished configuration, let’s take a look at the authentication and action. We’ll be able to see the GitHub login option shown on the web, and it’ll also be used from their command-line interaction. So let’s take a first look at login in the web and then login via tsh. So now, if we go to the Teleport web homepage, we can select GitHub. We enter in our “exampleoncall” user and their password. We’ll also enter in the two-factor authentication as now required. This will take us back to Teleport, and we have access to our cluster. We can see our full nodes, and this user has a monitor login they can use. So it’s like that.

Set GitHub as the default auth connector

Steven: And now we’ve opened up an SSH session, and we can access parts of the database as allowed for this user. Now, moving to the command line, we’re going to log in with the other user, the “exampleadminoncall” user, enter their username and password to get into GitHub. Again, enter the two-factor authentication, verify that. We can now see our status in the command line, what logins we have access to. So that’s going to open up a route login to the builder node. And again, we have an SSH session. We can run various commands. Now, in addition to SSH access, we also have our Kubernetes access. So let’s take a look at interacting with that. Remember, this user has the “system:masters” group access, so we can take a look at the default deployments. We can look at the pods and the default namespace. And we’re going to go ahead and delete one of these pods, which is just a “masters” group — is allowed to do, and that pod will automatically be recreated. You could see — it was just created. Let’s go ahead and open up an exec session into that pod. And now, just like an SSH session, we have access, and we can run commands.


Steven: So let’s review what we’ve done today. We’ve authenticated with GitHub users into Teleport in web and command-line interfaces. We’ve mapped teams within the GitHub organization to logins and Kubernetes usage within Teleport. We’ve configured the OAuth settings within the GitHub organization that allows Teleport to authenticate against that organization. We’ve configured a GitHub auth connector within Teleport that tells it to log into Kubernetes mappings. We’ve set that GitHub as the default auth connector for all users. And lastly, the steps that we’ve completed here are available within the Teleport documentation at this URL. We thank you for joining us for this video, and we hope that you visit our site and review our latest information.

Key links:

Share this page

Try Teleport today

In the cloud, self-hosted, or open source

View Developer Docs

This site uses cookies to improve service. By using this site, you agree to our use of cookies. More info.