Skip to content

Commit

Permalink
Add "How it works" to the GitHub SSO guide (#49284)
Browse files Browse the repository at this point in the history
Closes #44945

Add the required "How it works" section to the GitHub SSO guide. Use
this as a jumping off point to mention the limitation in which GitHub
does not assign Teleport usernames to email addresses.
  • Loading branch information
ptgott authored Dec 2, 2024
1 parent 4154eb7 commit 1ffe97e
Showing 1 changed file with 28 additions and 0 deletions.
28 changes: 28 additions & 0 deletions docs/pages/admin-guides/access-controls/sso/github-sso.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,34 @@ 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.

## How it works

A Teleport administrator creates a GitHub authentication connector on the
Teleport Auth Service backend and requires Teleport users to authenticate
through GitHub by creating a cluster authentication preference.

When a user authenticates to Teleport, they receive instructions to finish
authenticating using GitHub. The Teleport Auth Service receives an OAuth 2.0
access token from GitHub and authenticates the token. (The GitHub authentication
connector acts as an OAuth 2.0
[client](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1).)

The Auth Service then issues short-lived TLS and SSH certificates to the user by
reading data from the OAuth 2.0 access token. In particular, the Auth Service:
- Maps the user's GitHub teams to Teleport roles in order to assign the user
permissions.
- Assigns the user's Teleport username to their GitHub username.

<Notice type="warning">

GitHub usernames are not formatted as email addresses. As a result, any Teleport
plugin that expects to send email to a user based on their Teleport username
will not work as expected. For example, the [PagerDuty Access Request
plugin](../access-request-plugins/ssh-approval-pagerduty.mdx) has this
limitation.

</Notice>

## Prerequisites

- A GitHub organization with at least one team.
Expand Down

0 comments on commit 1ffe97e

Please sign in to comment.