[v9] backport #10386 : Add documentation for ssh key extensions with github

docs/config.json

@@ -167,6 +167,10 @@
             {
               "title": "Joining Nodes via AWS EC2",
               "slug": "/setup/guides/joining-nodes-aws-ec2/"
+            },
+            {
+              "title": "Using Teleport's CA with GitHub",
+              "slug": "/setup/guides/ssh-key-extensions/"
             }
           ]
         },

docs/pages/access-controls/reference.mdx

@@ -85,7 +85,15 @@ spec:
     # if unspecified. If one or more of the user's roles has disabled
     # the clipboard, then it will be disabled.
     desktop_clipboard: true
-
+    # Specify a list of names and associated values to be included in user SSH keys.
+    # The key type can only be "ssh" and the mode can only be "extension".
+    # The name and value fields can be arbitrary strings and the value field
+    # supports variable interpolation.
+    cert_extensions:
+     - type: ssh
+       mode: extension
+       name: login@github.com
+       value: "{{ external.github_login }}"
   # The allow section declares a list of resource/verb combinations that are
   # allowed for the users of this role. By default, nothing is allowed.
   allow:

docs/pages/setup/guides.mdx

@@ -10,3 +10,4 @@ layout: tocless-doc
   - [EC2 tags as Teleport Nodes](./guides/ec2-tags.mdx). How to set up Teleport Node labels based on EC2 tags.
   - [Joining Nodes via AWS IAM Role](./guides/joining-nodes-aws-iam.mdx). Use the IAM join method to add Nodes to your Teleport cluster on AWS.
   - [Joining Nodes via AWS EC2 Identity Document](./guides/joining-nodes-aws-ec2.mdx). Use the EC2 join method to add Nodes to your Teleport cluster on AWS.
+  - [Using Teleport's Certificate Authority with GitHub](./guides/ssh-key-extensions.mdx). Use Teleport's short-lived certificates with GitHub's Certificate Authority.

docs/pages/setup/guides/ssh-key-extensions.mdx

@@ -0,0 +1,66 @@
+---
+title: Using Teleport's Certificate Authority with GitHub
+description:  How to use Teleport's short-lived SSH certificates with the GitHub Certificate Authority.
+---
+
+Teleport supports exporting user SSH certificates with configurable key extensions. This allows the Teleport CA to be used in conjunction with GitHub's support for SSH Certificate Authorities. This way, users can access their organizations' repositories with short-lived, signed SSH certificates.
+
+## Prerequisites
+
+- The Teleport Auth Service and Proxy Service v(=teleport.version=), either self hosted or deployed on Teleport Cloud.
+- The GitHub SSO authentication connector. For more information, see [GitHub SSO](../admin/github-sso.mdx).
+- Access to GitHub Enterprise and permissions to modify GitHub's SSH Certificate Authorities.
+
+## Step 1/3. Import the Teleport CA into GitHub
+
+In order to export the Teleport CA, execute the following command:
+
+```code
+$ tctl auth export --type=user | sed 's/^cert-authority //g'
+```
+
+Next, follow the instructions in the guide below to import your Teleport CA into GitHub:
+
+[Managing your organization's SSH certificate authorities](https://docs.github.com/en/organizations/managing-git-access-to-your-organizations-repositories/managing-your-organizations-ssh-certificate-authorities)
+
+The contents of the exported `teleport.ca` file should by pasted into the "Key" field after clicking "New CA".
+
+## Step 2/3. Configure the GitHub key extension
+
+Create or update a role to include the `cert_extensions` option. The value of `name` must be `login@github.com`.
+
+```yaml
+kind: role
+metadata:
+  name: developer
+spec:
+  options:
+     cert_extensions:
+       - type: ssh
+         mode: extension
+         name: login@github.com # required to be `login@github.com`.
+         value: "{{ external.logins }}"
+```
+
+## Step 3/3. Issue a user certificate
+
+A user certificate may be issued with the following command, where `<USERNAME>` is the Teleport user to generate the SSH certificate for:
+```code
+$ tctl auth sign --out out.cer --user=<USERNAME>
+```
+
+To test that authentication with this signed certificate is working correctly, SSH into `github.com` with your organization's user:
+```code
+$ ssh -i out.cer org-<ID>@github.com
+```
+If authentication is successful,  a "You've successfully authenticated" message should be displayed in the terminal.
+
+This newly generated certificate may then be used when interacting with GitHub over SSH by adding the following to the `~/.ssh/config` file:
+
+```code
+Host github.com
+ HostName github.com
+ IdentityFile path/to/out.cer
+```
+
+When using SSH Certificate Authorities, you should retrieve your GitHub repository's SSH URL from the GitHub UI so the correct SSH user is used for authentication. For more information, see [About SSH URLs with SSH certificates](https://docs.github.com/en/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities#about-ssh-urls-with-ssh-certificates).