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.
- Teleport role with access to maintaining
github
resources for usingtctl
from the Desktop. This is available in the defaulteditor
role.
-
A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 9.3.7.tctl versionTeleport v9.3.7 go1.17
tsh versionTeleport v9.3.7 go1.17
See Installation for details.
-
A running Teleport cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 9.3.7, which you can download by visiting the customer portal.tctl versionTeleport v9.3.7 go1.17
tsh versionTeleport v9.3.7 go1.17
-
A Teleport Cloud account. If you do not have one, visit the sign up page to begin your free trial.
-
The
tctl
admin tool andtsh
client tool version >= 9.3.8. To download these tools, visit the Downloads page.tctl versionTeleport v9.3.8 go1.17
tsh versionTeleport v9.3.8 go1.17
To connect to Teleport, log in to your cluster using tsh
, then use tctl
remotely:
tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 9.3.7
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 statusCluster myinstance.teleport.sh
Version 9.3.8
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:
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:
Finally, create the connector using tctl
:
tctl create github.yamlauthentication connector "github" has been created
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.
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.yamlcluster 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 logoutLogged 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