SSH certificate authentication for GitHub Enterprise Cloud

GitHub Enterprise Cloud now supports SSH certificates to give enterprises and organizations more control over how their members access their repositories. SSH certificates allow one SSH key (a certificate authority) to sign another SSH key, along with information about the developer it belongs to. Admins can upload the public key of their SSH certificate authority (CA) and begin issuing certificates for their members to use for Git authentication. Certificates can only be used for accessing repositories belonging to that enterprise or organization. Additionally, admins can require members to use certificates when accessing their repositories.

How is this different than an SSH key?

If you’re wondering how an SSH certificate is different than an SSH key you’re not alone. GitHub has supported SSH keys—cryptographic keys that securely identify individual users—from the very beginning. But SSH also has a specification that defines support for SSH certificates. SSH certificates allow one SSH key to sign another SSH key, resulting in an “SSH certificate”. A server that trusts the CA is able to verify the certificate’s signature and trust the certificate and its associated metadata.

How does it work?

To get a sense for how it all works and gives teams more control, let’s take a look at how an organization would set up their CA before signing keys. The configuration process for enterprises is very similar.

First, an organization uploads their SSH CA key. This is just a normal SSH key:

➜  ssh-keygen -t ed25519 -C ca@github.com -f ca
➜  cat ca.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOixUTX9ssW7bAaO6wTxXxJGRpVWNnqnOFwFZ1ceOxVn ca@github.com

An organization uploads the public key similar to how they would for a user’s normal SSH key. But, instead, they upload the public key to their organization’s “SSH Certificate Authorities” configuration page:

Note: Enterprises and organizations can require SSH certificates to access their repositories. This gives admins more control over which keys can be used to access their repositories. Once uploaded, members will have a new section in their SSH key management page to see the enterprises and organizations they belong to that have an SSH CA configured.

Once an organization has added their SSH CA, they can begin to issue certificates to access the organization’s repositories. For the sake of simplicity, let’s use a user’s normal SSH key as an example:

➜  ssh-keygen -t ed25519 -C user1@github.com -f user1
➜  cat user1.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGN4i6n6N2jdOXM1RUhLIcww1RnO6QaE3psgUXLewash user1@github.com

This key can now be signed by the SSH CA to create a certificate used to access repositories owned by the organization:

➜ ssh-keygen -O extension:login@github.com=user1 -s ca -V '+1d' -I user1@github.com -n user1 user1.pub
Signed user key user1-cert.pub: id "user1@github.com" serial 0 for user1 valid from 2019-08-09T12:26:00 to 2019-08-10T12:27:43

Individual SSH keys no longer need to be uploaded to a developer’s account to access organization repositories. If an SSH key has been signed by the CA key, the resulting certificate can be used to authenticate access to organization repositories. GitHub identifies the developer accessing the repository based on the “login@github.com” certificate extension, which must be included.

SSH certificates allow organizations to maintain sophisticated security policies, such as certificates that expire daily. The certificate we created in our example has an expiration of one day. Organizations can establish highly secure development workflows where, every morning, a developer fetches their daily certificate from a custom internal system or a readily available solution that is responsible for issuing them. This system can perform whatever authentication abides by the internal authentication requirements of that organization. The resulting certificate can be used to do all of a developer’s work on GitHub.com for the day. And at the end of the day, the certificate automatically expires, and the developer is no longer be able to access any of that organization’s repositories. 

This is a highly requested feature from some of the most security-conscious teams around the world. We’re glad to give them—and all of the teams who use GitHub Enterprise—more ways to keep their code safe. And stay tuned: SSH certificate authentication support for Enterprise Server is coming soon.

Learn more about certificate authentication for GitHub Enterprise

Written by

Ben Toews

@mastahyeti