From 76d190c2e607c94462aed765703d5dbeef9c765e Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Tue, 19 Nov 2024 13:47:44 -0500 Subject: [PATCH] Add "How it works" to the GitHub SSO guide 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. --- .../access-controls/sso/github-sso.mdx | 28 +++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/pages/admin-guides/access-controls/sso/github-sso.mdx b/docs/pages/admin-guides/access-controls/sso/github-sso.mdx index 4159d565fdaab..9e34f0bbb94c5 100644 --- a/docs/pages/admin-guides/access-controls/sso/github-sso.mdx +++ b/docs/pages/admin-guides/access-controls/sso/github-sso.mdx @@ -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. + + + +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. + + + ## Prerequisites - A GitHub organization with at least one team.