Git-Credential-Manager-for-Windows

Secure Git credential storage for Windows with support for Visual Studio Team Services, GitHub, and Bitbucket multi-factor authentication.

Git Credential Manager for Windows

NOTICE: This project is no longer being maintained. :warning:

Git Credential Manager for Windows is no longer being maintained. The cross-platform Git Credential Manager Core (GCM Core) is the official replacement.

GCM Core is included as an optional component of Git for Windows 2.28 and will be made the default credential helper as of Git for Windows 2.29. GCM Core can also be manually installed from this page.

NOTICE: Experiencing GitHub push/fetch problems?

GitHub will disable password-based authentication on APIs Git Credential Manager for Windows uses to create tokens. As a result, GCM for Windows will no longer be able to create new access tokens for GitHub.

Git Credential Manager Core (GCM Core) supports OAuth-based authentication with GitHub and is the replacement for GCM for Windows.

Please update to Git for Windows 2.28 and select “Git Credential Manager Core” from the installer when asked to “select a credential helper”, or manually install GCM Core from here.

As of 22 Feb 2018, GitHub has disabled support for weak encryption which means many users will suddenly find themselves unable to authenticate using a Git for Windows which (impacts versions older than v2.16.0). DO NOT PANIC, there’s a fix. Update Git for Windows to the latest (or at least v2.16.0).

The most common error users see looks like:

If, after updating Git for Windows, you are still having problems authenticating with GitHub, please read this Developer Community topic which contains additional remedial actions you can take to resolve the problem.

If you are experiencing issue when using Visual Studio, please read Unable to connect to GitHub with Visual Studio.

The Git Credential Manager for Windows (GCM) provides secure Git credential storage for Windows. It’s the successor to the Windows Credential Store for Git (git-credential-winstore), which is no longer maintained. Compared to Git’s built-in credential storage for Windows (wincred), which provides single-factor authentication support working on any HTTP enabled Git repository, GCM provides multi-factor authentication support for Azure DevOps, Team Foundation Server, GitHub, and Bitbucket.

This project includes:

• Secure password storage in the Windows Credential Store.
• Multi-factor authentication support for Azure DevOps.
• Two-factor authentication support for GitHub.
• Two-factor authentication support for Bitbucket.
• Personal Access Token generation and usage support for Azure DevOps, GitHub, and Bitbucket.
• Non-interactive mode support for Azure DevOps backed by Azure Directory.
• NTLM/Kerberos authentication for Team Foundation Server (see notes).
• Optional settings for build agent optimization.

Community

This is a community project so feel free to contribute ideas, submit bugs, fix bugs, or code new features. For detailed information on how the GCM works go to the wiki.

Download and Install

To use the GCM, you can download the latest installer. To install, double-click GCMW-.exe and follow the instructions presented.

When prompted to select your terminal emulator for Git Bash you should choose the Windows’ default console window, or make sure GCM is configured to use modal dialogs. GCM cannot prompt you for credentials, at the console, in a MinTTY setup.

Manual Installation

Note for users with special installation needs, you can still extract the gcm-.zip file and run install.cmd from an administrator command prompt. This allows specification of the installation options explained below.

Installation in an MSYS2 Environment

To use the GCM along with git installed with pacman in an MSYS2 environment, simply download a release zip and extract the contents directly into C:\msys64\usr\lib\git-core (assuming your MSYS2 environment is installed in C:\msys64 ). Then run:

How to use

You don’t. It magically works when credentials are needed. For example, when pushing to Azure DevOps, it automatically opens a window and initializes an oauth2 flow to get your token.

Build and Install from Sources

To build and install the GCM yourself, clone the sources, open the solution file in Visual Studio, and build the solution. All necessary components will be copied from the build output locations into a .\Deploy folder at the root of the solution. From an elevated command prompt in the .\Deploy folder issue the following command git-credential-manager install . Additional information about development and debugging are available in our documents area.

Various options are available for uniquely configured systems, like automated build systems. For systems with a non-standard placement of Git use the —path parameter to supply where Git is located and thus where the GCM should be deployed to. For systems looking to avoid checking for the Microsoft .NET Framework and other similar prerequisites use the —force option. For systems looking for silent installation without any prompts, use the —passive option.

Additional Resources

Contribute

There are many ways to contribute.

• Submit bugs and help us verify fixes as they are checked in.
• Review code changes.
• Contribute bug fixes and features.

Code Contributions

For code contributions, you will need to complete a Contributor License Agreement (CLA). Briefly, this agreement testifies that you grant us permission to use the submitted change according to the terms of the project’s license, and that the work being submitted is under the appropriate copyright.

Please submit a Contributor License Agreement (CLA) before submitting a pull request. You may visit https://cla.microsoft.com to sign digitally. Alternatively, download the agreement Microsoft Contribution License Agreement.pdf, sign, scan, and email it back to cla@microsoft.com. Be sure to include your GitHub user name along with the agreement. Once we have received the signed CLA, we’ll review the request.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

License

This project uses the MIT License.

This project is maintained by microsoft

Hosted on GitHub Pages — Theme by orderedlist

Git-Credential-Manager-for-Windows

Secure Git credential storage for Windows with support for Visual Studio Team Services, GitHub, and Bitbucket multi-factor authentication.

If you have an issue using GCM or Askpass, please review the following FAQ and check our issue history or our Twitter feed before opening up an item on our issues page on GitHub.

Q: Why am always prompted for my username and password?

Most likely, your environment is not configured correctly. You can verify that your environment is configured correctly by running git config —list and looking for credential.helper=manager . If you do not see the line, then you know that Git does not know about the Git Credential Manager. You can configure Git to use the Credential Manager by running git config credential.helper manager .

Q: Why does my GUI freeze when I push, pull, or fetch?

Most likely reason is that your GUI “shells out” to git.exe to perform Git operations. When it does so, it cannot respond to the command line prompts for username and password like a real user can. To avoid being asked for your credentials on the command line, and instead be asked via a modal dialog you’ll need to configure the Git Credential Manager.

1. Decide if you want this to be a global setting (all of your repositories) or a local setting (just one repository).
2. Start your favorite shell (CMD, PowerShell, bash, etc.).
3. Update your settings, so that Git Credential Manager knows to display a dialog and not prompt at the command line:
   • If you’ve decided this is a global setting run git config —global credential.modalprompt true .
   • If you’ve decided this a per repository setting, cd to your repo and in that repo run git config credential.modalprompt true .

Q: Why am I not seeing my SSH keys being saved?

The Git Credential Manager supports caching of SSH key password through git-askpass. Unfortunately, OpenSSH will only interact with an askpass helper if there no TTY detected (no console available). This mean, in general and for the vast majority of users, the GCM does not help with SSH passwords or certificates.

Fortunately, the Posh-Git support automatic startup of ‘ssh-agent.exe’ which does assist with SSH certificate password caching.

Q: Is there a NuGet Package available?

Yes there is: https://www.nuget.org/packages/Microsoft.Alm.Authentication. It supports the core authentication library and the VSTS specific components. If you’re looking to extend the GCM, or need a way to authenticate with VSTS but cannot leverage the GCM directly, then it is likely what you’re after.

Q: Why doesn’t Git Credential Manager work on Windows XP, Mac OS, or Linux?

The Git Credential Manager does not work on Windows XP, Max OS, or Linux because we had to scope our work and we decided to support the same operating systems that Visual Studio support. Why Visual Studio? Well, because it is our favorite IDE and in order to support Azure DevOps we had to use the Azure Directory Authentication Libraries which only have multi-factor interactive logon support in their .NET libraries. Using .NET means using Visual Studio (which we love anyways) and using Visual Studio means Windows 7 or newer.

Q: Will there ever be support for Windows XP, Mac OS, or Linux?

We can safely say that we have no interest in supporting Windows XP. Even Microsoft has ended support for Windows XP. Support for Mac OS and Linux are handled by Microsoft Git Credential Manager for Mac and Linux.

Q: Why is my distribution/version of Git not supported? Why is Git for Windows favored?

The Credential Manager deployment helpers ( install.cmd and GCMW-.exe ) are focused on support for Git for Windows because Git for Windows conforms to the expected/normal behavior of software on Windows. It is easy to detect, has predictable installation location, etc. This makes supporting it easier and more reliable.

That said, so long as your favorite version of Git supports Git’s git-credential flow, it is supported by the Git Credential Manager for Windows. Setup will have to be manual, and if you find a way to script it we would love to have you contribute that to our project.

1. Copy the contents of the gcm- .zip to your Git’s /bin folder. This varies per distribution, but it is likely next to other git tools like git-status.exe .
2. Update your Git configuration by running git config —global credential.helper manager .

Q: I thought Microsoft was maintaining this, why does the GCM not work as expected with TFS?

Team Foundation Server, when deployed on a corporate Active Directory, uses the Microsoft Kerberos protocol for authentication. Git hasn’t traditionally be able to “speak” the Kerberos protocol. However, starting with v1.14.0 Git for Windows supports Microsoft Secure Channel. To enable Secure Channel support run git config —global http.sslBackend=schannel or selecting the ‘Native Windows Secure Channel library’ option during installation of Git for Windows. Secure Channel provides better integration with Windows’ networking and certificate management; enabling easier use of proxies and alternate authentication mechanisms previously unavailable to Git for Windows users.

Git needs to be convinced to “forward” credentials by supplying a blank credential set (username and password). The GCM will attempt to detect the Team Foundation Server via the HTTP headers returned when an unauthenticated request is handled by the server. If the server is configured to allow NTLM as a supported authentication protocol, the GCM will detect the setting and instruct Git to use NTLM instead of basic authentication.

Alternatively, you can configure the GCM to assume a host supports NTLM without checking. To do so, update your Git configuration by running git config —global credential..authority NTLM , where can be replaced by the host name of your TFS server; the port number is not required for GCM configuration but you will want it for the Git remote.

Note: Previous versions of the GCM suggested using git credential..integrated true ; while this configuration option continues to work, it has been deprecated in favor of specifying the correct authority.

Once updated, the new configuration tells the GCM to only negotiate via NTLM with the host and forward Windows credentials. Most likely, this is not what you want. Therefore, it strongly suggested that you restrict the configuration setting to the URL of your TFS Git host.

Q: Why doesn’t SourceTree use the credentials in the GCM?

You need to configure SourceTree to use the version of Git installed for the entire system. By default, SourceTree uses a local copy of portable Git.

To fix this go to ‘Tools > Options > Git’ and click the ‘Use System Git’ button. This works in v1.8.3.0 of SourceTree.

Q: Why is Git not using the GCM in some of my repositories (but instead using SSH authentication)?

Check that you are using the HTTP(S) URL instead of the SSH URL for your repository. You can do this by running git remote show origin . The Fetch URL and Push URL should start with https:// or http:// . If this is not the case, look for the HTTP(S) URL in the web interface of Azure DevOps, TFS, GitHub or Bitbucket, and then run git remote set-url origin , where is the HTTP(S) URL.

Q: Why is git.exe failing to authenticate after linking/unlinking your Azure DevOps account from Azure Active Directory?

When the tenant backing the Azure DevOps account changes like when you Connect VSTS account to Azure Active Directory (Azure AD), the tenant cache needs to be cleared if you’re using a GCM version prior to v1.15.0. Clearing the tenant cache is as easy as deleting the %LocalAppData%\GitCredentialManager\tenant.cache file on each machine returning a login error like below. The GCM will automatically recreate and populate the cache file as needed on subsequent login attempts.

Q: Why doesn’t the GCM work with ServicePointManager?

When you have git config http.proxy or HTTPS_PROXY configured to use ServicePointManager proxy, and the URL doesn’t begin with http:// the GCM will be unable to negotiate with the proxy. This is due the way the .NET Framework WebProxy and ServicePointManager interact. You can read “ServicePointManager does not support proxies of https scheme” for additional information about this issue.

The work around is to use a proxy URL which starts with http:// , or discontinue use of ServicePointManager .

This project is maintained by microsoft

Hosted on GitHub Pages — Theme by orderedlist