teleport/docs/pages/setup/admin/github-sso.mdx

---
title: Set up Single Sign-On with GitHub
description: Setting up Github SSO
videoBanner: XjgN2WWFCX8
---

This guide explains how to set up Github Single Sign On (SSO) for Teleport.

## Prerequisites

<Tabs>
<TabItem scope={["oss"]} label="Self-Hosted">
- Install Teleport and the `tctl` admin tool version >= (=teleport.version=).

  See [Installation](../../installation.mdx) for details.

- Create and register a GitHub OAuth App. To do so, follow the instructions in
  GitHub's documentation.

  [Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app)

  Ensure that your OAuth App's "Authentication callback URL" is
  `https://PROXY_ADDRESS/v1/webapi/github/`, where `PROXY_ADDRESS` is the public
  address of the Teleport Proxy Service.
</TabItem>
<TabItem
  scope={["enterprise"]} label="Enterprise">
- Install Teleport and the `tctl` admin tool version >= (=teleport.version=).

  To download Teleport Enterprise, visit the
  [customer portal](https://dashboard.gravitational.com/web/login).

- Create and register a GitHub OAuth App. To do so, follow the instructions in
  GitHub's documentation.

  [Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app)

  Ensure that your OAuth App's "Authentication callback URL" is
  `https://PROXY_ADDRESS/v1/webapi/github/`, where `PROXY_ADDRESS` is the public
  address of the Teleport Proxy Service.
</TabItem>
<TabItem scope={["cloud"]}
  label="Cloud">

- Sign up for a Teleport Cloud account. If you do not have one, visit the
  [sign up page](https://goteleport.com/signup/) to begin your free trial.

- Create and register a GitHub OAuth App. To do so, follow the instructions in GitHub's documentation.

  [Creating an OAuth App](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app)

  Ensure that your OAuth App's "Authentication callback URL" is
  `https://PROXY_ADDRESS/v1/webapi/github/`, where `PROXY_ADDRESS` is the domain
  name of your Teleport Cloud tenant (e.g., mytenant.teleport.sh).

</TabItem>
</Tabs>

(!docs/pages/includes/tctl.mdx!)

## Step 1/2. Create a GitHub authentication connector

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

```yaml
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](https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/)

Finally, create the connector using `tctl`:

```code
$ tctl create github.yaml
```

<Admonition type="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.
</Admonition>

## Step 2/2. Configure authentication preference

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

Create a file called `cap.yaml` with the following content:

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

Create the resource:

```code
$ tctl create -f cap.yaml
```

<Details scope={["enterprise", "oss"]} scopeOnly={true} opened title="Static configuration file">

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

```yaml
# Snippet from /etc/teleport.yaml
auth_service:
  authentication:
    type: github
```
</Details>

You can now log in with Teleport using GitHub SSO.

## Troubleshooting

(!docs/pages/includes/sso/loginerrortroubleshooting.mdx!)