Skip to content

Commit

Permalink
update enterprise pre-req
Browse files Browse the repository at this point in the history
  • Loading branch information
greedy52 committed Jan 6, 2025
1 parent 9a16b7f commit 3f799da
Show file tree
Hide file tree
Showing 3 changed files with 22 additions and 10 deletions.
13 changes: 7 additions & 6 deletions docs/pages/admin-guides/management/guides/github-integration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@ title: GitHub Integration
description: How to use Teleport's short-lived SSH certificates with the GitHub Certificate Authority.
---

Teleport can proxy Git commands and use short-lived SSH certificate to
authenticate GitHub organizations that trust Teleport's certificate authorities.
Teleport can proxy Git commands and use short-lived SSH certificates to
authenticate GitHub organizations.

In this guide, you will:
- Create a GitHub OAuth application.
Expand All @@ -17,26 +17,27 @@ In this guide, you will:
GitHub enables organizations to configure a list of SSH Certificate Authorities
(CAs) for authentication. This feature allows access to the organization's
repositories using short-lived SSH certificates signed by an approved CA, such
as a Teleport CA. Additionally, organizations can enforce stricter security by
as a Teleport CA. Optionally, organizations can enforce stricter security by
requiring these signed SSH certificates for access, effectively disabling the
use of personal SSH keys and access tokens.

Teleport users can configure their Git repositories to proxy through Teleport.
After setup, Git commands automatically route through Teleport, which
impersonates their GitHub identities using short-lived SSH certificates signed
by Teleport's CA for authentication with GitHub.
by Teleport's CA for authentication with GitHub. Each Git command proxied
through Teleport is also logged in Teleport's audit events.

To retrieve a user's GitHub identity, `tsh` initiates the GitHub OAuth flow by
opening a browser window for the user to log in with their GitHub credentials.

![GitHub SSH certificate authorities](../../../../img/management/how-it-works-github-proxy.svg)

Note that Teleport proxies Git commands through SSH but the users should
continue to access github.com regularly through their browsers.
continue to access github.com website regularly through their browsers.

## Prerequisites

- Teleport Enterprise or Teleport Enterprise Cloud cluster version 17.2 or higher.
(!docs/pages/includes/edition-prereqs-tabs-enterprise.mdx version="17.2"!)
- Access to GitHub Enterprise and permissions to modify GitHub's SSH certificate
authorities and configure OAuth applications.
- (!docs/pages/includes/tctl.mdx!)
Expand Down
8 changes: 4 additions & 4 deletions docs/pages/connect-your-client/includes/tsh-git.mdx
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
Use `tsh git ls` to view a list of GitHub organizations you have access to:
```code
$ tsh git ls
Type Organization Username URL
------ ------------- ----------- --------------------------------
GitHub my-github-org my-username https://github.com/my-github-org
Type Organization Username URL
------ ------------- -------- --------------------------------
GitHub my-github-org my-user https://github.com/my-github-org
```

Teleport requires your GitHub identity to impersonate you. If you haven't
Expand All @@ -12,7 +12,7 @@ provided it yet, run the following command:
$ tsh git login --github-org my-github-org
If browser window does not open automatically, open it by clicking on the link:
http://127.0.0.1:55555/some-id
Your GitHub username is my-username.
Your GitHub username is my-user.
```

This command opens a browser, prompting you to authenticate with GitHub via the
Expand Down
11 changes: 11 additions & 0 deletions docs/pages/includes/edition-prereqs-tabs-enterprise.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
{{ version="(=teleport.version=)" }}

- A running Teleport Enterprise cluster version {{ version }} or above. If you
want to get started with Teleport, [sign up](https://goteleport.com/signup)
for a free trial or [set up a demo
environment](../admin-guides/deploy-a-cluster/linux-demo.mdx).

- The `tctl` admin tool and `tsh` client tool.

Visit [Installation](../installation.mdx) for instructions on downloading
`tctl` and `tsh`.

0 comments on commit 3f799da

Please sign in to comment.