Contents
Summary
Cornell’s GitHub Enterprise service consists of a web site and an API for Git clients. Accessing this site requires use of Cornell’s Single Sign On solution as is standard across Cornell services. When interacting with your repositories in a local environment, a Git client is used to interact with repositories (and more) under the user’s account.
Authentication Methods
While individual Git clients are many, they all ultimately have two ways of communicating with the GitHub system:
- Using an HTTPS URL https://github.coecis.cornell.edu/[user]/[repo].git
- Using an SSH URL git@github.coecis.cornell.edu:[user]/[repo].git
When cloning a repository via HTTPS, a username and password is required. Unfortunately, due to the Single Sign On implementation, users cannot use their Cornell credentials directly in most cases. GitHub has a solution for this in the form of Personal Access Tokens (PATs). Then there is the SSH method which uses existing SSH key-authentication to establish access. The preferred method from a security perspective is Personal Access Tokens (PATs), as they can restrict access for a specific use-case.
Some Git clients (including the Git Credential Manager) use your browser to allow you to authenticate using SSO. This is not always a viable option, such as when connected to a remote Linux server on the command line.
HTTPS Authentication
Cloning a repository using the HTTPS link will require authenticating with the user’s NetId and a Personal Access Token. All communications with the GitHub server will be performed using standard web traffic and is secured using SSL/TLS.
Personal Access Tokens
Github provies the ability to generate Personal Access Tokens (PAT) to use in place of your password for applications which require http authentication. Using a PAT allows you to access the features of your account and are easily replacable if access to the environment is lost. These PATs come in two varieties, Fine-Grained, and Classic. Using a PAT is as simple as pasting it into the passowrd prompt in your Git Client.
Fine-Grained PAT
As the name suggests, creating a fine-grained token is a highly configurable, detailed process. They provide the highest level of granular permissions, allowing a user to refine a token down to certain behaviors on specific repositories. These are excellent when using shared or untrusted environments like a shared workstation or server, but involve additional overhead as you must define access to specific repositories, behaviors, and a required expiration date.
Classic PAT
Creating a Classic PAT is useful when setting up a dedicated workstation as one token will work for all repositories. This is also useful for setting up a Git Client which offers rich feature integration as the Classic PAT is more permissive, granting access to all organization repositories accessible by your account in addition to your personal repositories.
Securing your tokens
Similar to passwords, tokens must be kept in a secure manner. There are several ways to do this, but we will focus on officially supported GitHub CLI and the Git Credential Manager.
GitHub CLI
GitHub CLI is a fully-feature command line interface to the Cornell GitHub environment. It is not the same as the standard Git binary in wide use. It allows you to manage your repositories, pull requests, releasts, and more. This guide will focus on the authentication functionality, which is automatically used by the standard Git command as well as the GitHub CLI
After installing GitHub CLI, from a terminal on your operating system type: gh auth login --hostname github.coecis.cornell.edu. This will prompt you for your token, which you can paste into the terminal. This will work for both fine-grained and classic tokens. Once authenticated, you can continue to use the GitHub CLI or use the plain Git client with the permissions assigned to that token.
Git Credential Manager
Installing Git Credential Manager will add a new module to the git command. To login, use a terminal to run the following: git credential-manager github login --url https://github.coecis.cornell.edu. This will open a UI dialog allowing you to authenticate via a browser (using Cornell SSO), or via a token. After you use this tool, the Git command line tool will automatically operate with the permissions of your user (if you login with the browser), or your token (if you chose that option).
SSH Authentication
The oldest method of authenticating to a git provider, SSH Key Authentication makes use of the Secure Shell (SSH) protocol for communications. This usually requires a deeper understanding of SSH Clients and Key Management, but is an effective and secure way of establishing credentials via public-private key cryptography.
To get started, you will need to generate a new SSH key and add the key to your ssh-agent. Once you’ve got your key in place, you will need to add the ssh key to your Cornell GitHub Enterprise account. After which, you’ll need to test your SSH connection. If you run into any problems, please consult the GitHub documentation for troubleshoooting SSH issues. If you find you are still unable to access Cornell GitHub Enterprise, please submit a ticket to the ITSG Help Desk.
Once this is operational, Git will automatically be authenticated only for repositories cloned via the SSH method.
Checking Existing Repository Authentication
You can check how your repository was cloned by showing the remote URL using the following command: git remote -v. Compare the results with these remote URL patters. If you have repositories which were cloned using the HTTPS method and you are using SSH, you can easily switch the remote to SSH. Alternatively, if your repository is using SSH and you’re switching to HTTPS, simply switch the remote to HTTPS.