Git Credential Manager Core: Building a universal authentication experience

Authentication is a critical component to your daily development. When working in open source, you need to prove that you have rights to update a branch with git push. Additionally when working on proprietary software, you need a way to prove that you even have read permission to access your code during git fetch or git pull.

Git currently supports two authentication mechanisms for accessing remotes. When using HTTP(S), Git sends a username and password, or a personal access token (PAT) via HTTP headers. When using SSH, Git relies on the server knowing your machine’s public SSH key. Though SSH-based authentication is considered most secure, setting it up correctly can often be a challenge. On the other hand, PATs are often much easier to set up, but also far less secure.

To manage all of this, Git relies on tools called credential managers which handle authentication to different hosting services. When first designed, these tools simply stored usernames and passwords in a secure location for later retrieval (e.g., your keychain, in an encrypted file, etc). These days, two-factor authentication (2FA) is commonly required to keep your data secure. This complicates the authentication story significantly since new and existing tools are required to meet the demands of these stricter authentication models.

Even though authentication is so critical, building a new authentication feature is hard. Hard to debug, hard to test, hard to get right. If you’re going to do something, then it is best to do it right. Even better, it is helpful to do it once. We’ve been hard at work laying the foundation for a single tool to unify the Git authentication experience across platforms and hosting services.

I’m pleased to announce a new credential manager is available for Windows and macOS: Git Credential Manager (GCM) Core! GCM Core is a free, open-source, cross-platform credential manager for Git, and currently supports authentication to GitHub, Bitbucket, and Azure Repos. We built this tool from the ground up with cross-platform and cross-host support in mind. We plan to extend this tool to include support for Linux platforms and authentication with additional hosting services.

But wait? Doesn’t this just mean we’ve made yet another credential helper?

xkcd on Standards. Source: xkcd.com – License

Well yes, but actually no. GCM Core is in beta today, which means that we won’t be retiring GCM for Windows. Also without Linux support we won’t be retiring GCM for Mac & Linux, just yet.

However, once GCM Core has had some time in the wild, we will move to deprecate and retire both GCM for Windows and GCM for Mac & Linux.

Try out GCM Core today

To install GCM Core, follow these instructions for each platform:

Windows

GCM Core is distributed as a standalone installer which you can find from the releases page on GitHub. The next version of the official Git for Windows installer will include GCM Core as an experimental option, and eventually will become installed by default.

GCM Core installs side-by-side with existing Git Credential Manager for Windows installations and will re-use any previously stored credentials. This means that you do not need to re-authenticate! Credentials created by GCM Core are also backwards compatible with GCM for Windows, should you wish to return to the older credential manager.

Switching back to GCM for Windows

If you installed GCM Core via the Git for Windows installer, you can run the following in an admin command-prompt to switch back to using GCM for Windows:

git config --system --unset credential.https://dev.azure.com.useHttpPath 
git config --system credential.helper manager

If you installed GCM Core via the standalone installer, simply uninstall GCM Core from the Control Panel or Settings app.

macOS

GCM Core is available from the custom Microsoft Homebrew Tap and can be installed and configured for the current user easily by running the following commands with Homebrew installed:

brew tap microsoft/git 
brew cask install git-credential-manager-core

Toward a universal authentication experience

We intend for GCM Core to be helpful for all users, on all platforms, using any hosting service. There is room to grow here, especially our plans to make GCM Core available on Linux.

We are pleased our first release has support for authenticating with GitHub, Azure Repos, and Bitbucket. In particular, we would like to thank @mminns for helping us get the Bitbucket authentication mechanism working! We are excited to similarly extend support for other hosting services, including planned support for GitLab.

Using GCM Core

While authentication is critical to user success, it isn’t something that should take a lot of user attention. We streamlined the authentication flow to ensure that you are prompted for new credentials only when absolutely necessary. This flow includes interactive sessions that allow a variety of 2FA mechanisms.

On Windows, our authentication model uses a graphical user interface (GUI) system. The authentication windows are custom to your Git hosting service, as seen in the figure below.

On macOS, the authentication process uses a combination of terminal inputs and browser windows.

We are working on updating this terminal-based approach with a cross-platform GUI approach. This again will help unify the authentication user experience across platforms.

After completing the GUI steps to create a security token, these credentials are securely stored. On Windows, the tokens are stored in the Windows Credential Manager. This is backwards compatible with any existing GCM for Windows credentials. On macOS, credentials are securely stored in the user’s login Keychain.

A brief history of GCM

I mentioned earlier that we are laying a foundation for a unified authentication experience. It may help to understand the fractured world of Git authentication before GCM Core.

The Git Credential Manager for Windows (GCM for Windows) was created back in 2015 primarily to address the combined problem of a lack of SSH support in Azure Repos, then named Visual Studio Online, and a hard requirement for 2FA for many Azure Active Directory or Microsoft Account users – the authentication providers supported by Azure Repos. Over time GCM for Windows also gained support for GitHub and Bitbucket authentication through open-source contributions. Git for Windows initially shipped only with a C-based credential helper named wincred which just persisted a username/password, and did nothing regarding 2FA.

At the same time, Git Credential Manager for Mac and Linux (GCM for Mac & Linux) was created, focused on non-traditional Microsoft developers. That is, those not on Windows and those using non-Microsoft languages, runtimes, or toolchains.

These two codebases are completely separate, with GCM for Windows being written in C# and GCM for Mac & Linux being written in Java. GCM for Mac & Linux is also limited to Azure Repos and never got any support for GitHub or Bitbucket. Both projects have had their fair share of issues (remember: auth is hard). With the number of different authentication topologies typically present in enterprises means there’s been a number of dirty hacks added over the years to work around problems quickly.

After seeing the success of moving the Windows OS monorepo to Git, the Microsoft Office team approached our team with a desire to do the same with their monorepo. The catch: they have developers using macOS to build macOS and iOS clients. This means that they need cross-platform tools. As part of that, you can read about our journey to transition from the Windows-only VFS for Git to Scalar as a cross-platform solution for monorepo performance.

Scalar and VFS for Git are extensions to Git that make it easier to work with very large monorepos. Both of these technologies rely in part of the GVFS Protocol to receive information such as file sizes and individual objects on-demand from a remote repository. This mechanism only uses HTTP REST endpoints, and is not available via SSH. This means that it is even more important to have a proper credential manager on macOS.

We examined this landscape of credential managers and decided that they needed something better, and more sustainable. Thus, the idea of GCM Core was born.

With the release and introduction of .NET Core and .NET Standard, creating applications that work across Windows, macOS, and Linux is easy. The ability to bundle the .NET runtime with your application when publishing means you can distribute without worrying about runtime dependencies or mismatched versions.

Future work

Today is just the beginning. This first launch is a small, but important step toward unifying the authentication experience. Come along with us on this journey, and contribute to the open-source project by creating issues when you have a problem, or contributing a pull request if you can.

Linux distributions

We are working on getting GCM Core to Linux users of various distributions. The groundwork is already in place, and we’re just evaluating options for persisting credentials in a safe place. Consult this issue for the latest updates on Linux support.

Mac/Linux GUIs

Currently only Windows has GUIs for all the current Git host providers. macOS has a GUI only for Azure Repos. We are evaluating options such as Avalonia or native helper apps for this, and would happily welcome any contributions in this space. Consult this issue for the latest updates on cross-platform UI.

Written by

Matthew John Cheetham

@mjcheetham