title | description | videoBanner |
---|---|---|
Set up Single Sign-On with GitHub |
Setting up GitHub SSO |
XjgN2WWFCX8 |
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.
-
A GitHub organization with at least one team.
In Teleport Community Edition and Teleport Team, this organization must not have external SSO set up, or Teleport will refuse to create the GitHub authentication connector.
In Teleport Enterprise and Enterprise Cloud, organization can be hosted from either GitHub Cloud or GitHub Enterprise Server.
-
Teleport role with access to maintaining
github
resources for usingtctl
from the Desktop. This is available in the defaulteditor
role.
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
- (!docs/pages/includes/tctl.mdx!)
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/
Replace PROXY_ADDRESS
with be the public address of the Teleport Proxy Service
or your Teleport Cloud workspace URL (e.g., example.teleport.sh
).
The app must have the read:org
scope in order to be able to read org and team
membership details.
Instructions for creating a GitHub OAuth app are available in GitHub's documentation
Create a client secret to use along with the client ID in the next step:
In this section, you will define a GitHub authentication connector using tctl
.
On your workstation, create a file called client-secret.txt
consisting only of
your client secret.
Update this example command with:
- Your OAuth app's client ID and client secret created during the previous step.
- The roles you want to map from your GitHub organization to Teleport roles. Roles are defined in the Repository roles section of your organization's settings.
See tctl sso configure github for a full reference of flags for this command:
$ tctl sso configure github \
--id=<Var name="GITHUB-CLIENT-ID"/> \
--teams-to-roles=<Var name="ORG-NAME,github-team,access,editor"/> \
--secret=$(cat client-secret.txt) \
> github.yaml
The contents of github.yaml
should resemble the following:
<TabItem scope={["enterprise", "cloud"]} label="Commercial">
kind: github
metadata:
name: github
spec:
api_endpoint_url: ""
client_id: <client-id>
client_secret: <client-secret>
display: GitHub
endpoint_url: ""
redirect_url: https://<proxy-address>/v1/webapi/github/callback
teams_to_logins: null
teams_to_roles:
- organization: org-name
roles:
- access
- editor
- reviewer
team: github-team
version: v3
$ tctl sso configure github \
--id=<Var name="GITHUB-CLIENT-ID"/> \
--teams-to-roles=<Var name="ORG-NAME,github-team,access,editor"/> \
--teams-to-roles="org-name,administrators,admins \
--teams-to-roles="different-org,developers,dev \
--secret=$(cat client-secret.txt) \
> github.yaml
spec.
teams_to_roles:
- organization: org-name
roles:
- access
- editor
team: github-team
- organization: org-name
roles:
- admins
team: administrators
- organization: different-org
roles:
- devs
team: developers
For self-hosted GitHub Enterprise servers, you can specify the server
instance endpoints with the --endpoint-url
, --api-endpoint-url
parameters:
$ tctl sso configure github \
--id=<Var name="GITHUB-CLIENT-ID"/> \
--teams-to-roles=<Var name="ORG-NAME,github-team,access,editor"/> \
--secret=$(cat client-secret.txt) \
--endpoint-url=https://<Var name="github-enterprise-server-address"/>
--api-endpoint-url=https://<Var name="api-github-enterprise-server-address"/>
> github.yaml
...
spec:
...
api_endpoint_url: https://<api-github-enterprise-server-address>
endpoint_url: https://<github-enterprise-server-address>
...
You can test the connector configuration before applying it to your cluster. This is strongly encouraged to avoid interruption to active clusters:
$ cat github.yaml | tctl sso test
If browser window does not open automatically, open it by clicking on the link:
http://127.0.0.1:52690/35714f6b-...
Success! Logged in as: alice
--------------------------------------------------------------------------------
Authentication details:
roles:
- access
- editor
traits:
github_teams:
- admins
kubernetes_groups: null
kubernetes_users: null
logins:
- alice
username: alice
--------------------------------------------------------------------------------
[GitHub] Received claims:
organization_to_teams:
Octocats:
- admins
teams:
- admins
username: alice
--------------------------------------------------------------------------------
[GitHub] Connector team to roles mapping:
- organization: Octocats
roles:
- access
- editor
team: admins
--------------------------------------------------------------------------------
For more details repeat the command with --debug flag.
Finally, create the connector using tctl
:
$ tctl create -f github.yaml
authentication connector "github" has been created
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:
'*': '*'
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 --auth=github
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
$ tsh logout
# Logged out all users from all proxies.
$ tsh login --proxy=mytenant.teleport.sh --auth=github
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
You can also log to the web UI using GitHub by clicking Other sign-in options at the login screen.
When you sign in for the first time, you will see a prompt to authorize your GitHub OAuth app:
Teleport will request only the read:org
OAuth scope. Read more about OAuth scopes in GitHub's documentation:
GitHub OAuth scopes
After logging in successfully, you will see the following:
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
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
<TabItem scope={["enterprise"]} label="Teleport Enterprise">
> Profile URL: https://tele.example.com:443
Logged in as: jeff
Cluster: tele.example.com
Roles: access, requester
Logins: jeff, ubuntu, debian
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
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
> Profile URL: https://mytenant.teleport.sh:443
Logged in as: jeff
Cluster: mytenant.teleport.sh
Roles: access, requester
Logins: jeff, ubuntu, debian
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
In the previous step we signed in to Teleport using GitHub credentials by
specifying GitHub as our auth type. By editing the cluster_auth_preference
resource we can make it the default auth type.
Edit the existing cluster_auth_preference
resource using tctl
:
$ tctl edit cap
A temporary file will open in your default editor with your cluster_auth_preference
definition.
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 or Teleport
Cloud workspace.
When you save and close the temporary file, tctl
will update the resource:
#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
After logging out of tsh
, you can log back in without specifying
--auth=github
. You will automatically be redirected to the GitHub auth flow.
(!docs/pages/includes/sso/loginerrortroubleshooting.mdx!)
If you are not seeing teams mapping to roles as expected confirm you
are using the slug of the organizations and teams in the connector.
To create the slug, GitHub replaces special characters in the name string,
changes all words to lowercase, and replaces spaces with a -
separator.
For example, "My TEam Näme" would become my-team-name
.
The GitHub Web application URLs and GitHub API can provide the slug.
Example: navigate to the team My Team
in the GitHub web application.
The URL https://github.com/orgs/org-name/teams/my-team
shows the slug is my-team
. Update the teams to roles mapping.
teams_to_roles:
- organization: my-org
roles:
- access
- editor
- reviewer
team: my-team