diff --git a/tutorials/protect-github-ssh.mdx b/tutorials/protect-github-ssh.mdx index fd949dda..ebd18ba3 100644 --- a/tutorials/protect-github-ssh.mdx +++ b/tutorials/protect-github-ssh.mdx @@ -1,5 +1,5 @@ --- -updated_at: September 02, 2026 +updated_at: October 05, 2026 title: Protect GitHub with SSH Certificates html_title: Protect GitHub Repositories with Hardware-Bound SSH Certificates description: Authenticate to GitHub with short-lived SSH certificates backed by your device's TPM or Secure Enclave, issued and managed by the Smallstep Agent. @@ -178,15 +178,16 @@ your GitHub Enterprise organization is configured to trust SSH certificates sign ## Retrieve your SSH CA public key -On a machine with the [`step` CLI](../step-cli/README.mdx) installed, -bootstrap with your team and print your SSH user CA public key: +In the Smallstep dashboard, go to **Protect → SSH** and copy the **SSH User CA pub Key**. + +Alternatively, on a machine with the [`step` CLI](../step-cli/README.mdx) installed, +bootstrap with your team and print the key: ```bash step ssh config --team [your team slug] step ssh config --roots ``` -The output is your SSH CA's public key. Copy the entire key; it will look similar to: ``` @@ -198,7 +199,7 @@ ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBK... 1. On GitHub, navigate to your organization's **Settings** 2. Under **Authentication security**, find **SSH certificate authorities** 3. Click **New CA** -4. Paste the public key from `step ssh config --roots` into the **Key** field +4. Paste your SSH user CA public key into the **Key** field 5. Click **Add CA** The CA now appears in your list of SSH certificate authorities, @@ -208,6 +209,15 @@ will be accepted for authentication to your organization's repositories. For more information, see [GitHub's documentation on SSH certificate authorities](https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-git-access-to-your-organizations-repositories/about-ssh-certificate-authorities). + +
+ To trust the CA across every organization in your enterprise, + an enterprise owner can instead add it under + Your enterprises → Settings → Authentication security → SSH certificate authorities. + See Managing SSH certificate authorities for your enterprise. +
+
+ ## Optional: Require SSH certificates GitHub Enterprise lets you **require SSH certificates** for all Git access to your organization's repositories, @@ -238,10 +248,8 @@ The agent's SSH socket location per platform:
The steps below make the Smallstep Agent's keys your only SSH agent keys. - For gradual adoption, you can instead scope the agent to specific projects: - tools like direnv can set SSH_AUTH_SOCK per directory, - and git supports conditional configuration with - [includeIf "env:SSH_AUTH_SOCK=..."] directives. + To keep your existing agent for other hosts, see + Optional: Scope the agent to GitHub instead.
@@ -276,6 +284,24 @@ Set the environment variable for your user: - **Variable value:** `\\.\pipe\step-agent-ssh` 4. Click **OK**, and restart any open terminal windows +## Optional: Scope the agent to GitHub + +If you'd rather not replace your default SSH agent, +leave `SSH_AUTH_SOCK` alone and point only `github.com` connections at the Smallstep Agent +with an `IdentityAgent` directive in `~/.ssh/config`. +For example, on macOS: + +``` +Host github.com + IdentityAgent "~/Library/Application Support/Smallstep/step-agent-ssh.sock" +``` + +Use the socket path for your platform from the table above. +All other SSH connections continue to use your existing agent. + +For project-scoped adoption, tools like `direnv` can set `SSH_AUTH_SOCK` per directory, +and `git` supports conditional configuration with `[includeIf "env:SSH_AUTH_SOCK=..."]` directives. + ## Verify SSH authentication Confirm the agent's certificate is available: