Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[v15] Add "How it works" to the GitHub SSO guide #49284

Merged
merged 1 commit into from
Dec 2, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading