diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index a7a7e0e63..46e9cffc1 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -73,6 +73,6 @@ available at [Contributor Covenant Code of Conduct][cc-coc]. For answers to common questions about this code of conduct, see the [Contributor Covenant FAQ][cc-faq] -[cc-homepage]: https://www.contributor-covenant.org [cc-coc]: https://www.contributor-covenant.org/version/1/4/code-of-conduct.html [cc-faq]: https://www.contributor-covenant.org/faq +[cc-homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 41c925a91..fad3f4f95 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,8 @@ # Contributing -[issue]: https://github.com/GitCredentialManager/git-credential-manager/issues/new/choose -[fork]: https://github.com/GitCredentialManager/git-credential-manager/fork -[pr]: https://github.com/GitCredentialManager/git-credential-manager/compare -[code-of-conduct]: CODE_OF_CONDUCT.md -[commits]: https://www.youtube.com/watch?v=4qLtKx9S9a8 - Hi there! We're thrilled that you'd like to contribute to GCM :tada:. Your help is essential for keeping it great. -Contributions to GCM are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE). +Contributions to GCM are [released][contribute-under-repo-license] to the public under the [project's open source license][license]. Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project you agree to abide by its terms. @@ -42,6 +36,17 @@ Here are a few things you can do that will increase the likelihood of your pull ## Resources -- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) -- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/) -- [GitHub Help](https://help.github.com) +- [How to Contribute to Open Source][how-to-contribute] +- [Using Pull Requests][prs] +- [GitHub Help][github-help] + +[code-of-conduct]: CODE_OF_CONDUCT.md +[commits]: https://www.youtube.com/watch?v=4qLtKx9S9a8 +[contribute-under-repo-license]: https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license +[fork]: https://github.com/GitCredentialManager/git-credential-manager/fork +[github-help]: https://help.github.com +[how-to-contribute]: https://opensource.guide/how-to-contribute/ +[issue]: https://github.com/GitCredentialManager/git-credential-manager/issues/new/choose +[license]: LICENSE +[pr]: https://github.com/GitCredentialManager/git-credential-manager/compare +[prs]: https://help.github.com/articles/about-pull-requests/ diff --git a/README.md b/README.md index b9a2d4be1..6cc051c90 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,27 @@ # Git Credential Manager -[![Build Status](https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml/badge.svg)](https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml) +[![Build Status][build-status-badge]][workflow-status] --- -[Git Credential Manager](https://github.com/GitCredentialManager/git-credential-manager) (GCM) is a secure Git credential helper built on [.NET](https://dotnet.microsoft.com) that runs on Windows, macOS, and Linux. +[Git Credential Manager][gcm] (GCM) is a secure Git credential helper built on [.NET][dotnet] that runs on Windows, macOS, and Linux. -Compared to Git's [built-in credential helpers](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage) (Windows: wincred, macOS: osxkeychain, Linux: gnome-keyring/libsecret) which provides single-factor authentication support working on any HTTP-enabled Git repository, GCM provides multi-factor authentication support for [Azure DevOps](https://dev.azure.com/), Azure DevOps Server (formerly Team Foundation Server), GitHub, Bitbucket, and GitLab. +Compared to Git's [built-in credential helpers][git-tools-credential-storage] (Windows: wincred, macOS: osxkeychain, Linux: gnome-keyring/libsecret) which provides single-factor authentication support working on any HTTP-enabled Git repository, GCM provides multi-factor authentication support for [Azure DevOps][azure-devops], Azure DevOps Server (formerly Team Foundation Server), GitHub, Bitbucket, and GitLab. -Git Credential Manager (GCM) replaces the .NET Framework-based [Git Credential Manager for Windows](https://github.com/microsoft/Git-Credential-Manager-for-Windows) (GCM), and the Java-based [Git Credential Manager for Mac and Linux](https://github.com/microsoft/Git-Credential-Manager-for-Mac-and-Linux) (Java GCM), providing a consistent authentication experience across all platforms. +Git Credential Manager (GCM) replaces the .NET Framework-based [Git Credential Manager for Windows][gcm-for-windows] (GCM), and the Java-based [Git Credential Manager for Mac and Linux][gcm-for-mac-and-linux] (Java GCM), providing a consistent authentication experience across all platforms. ## Current status Git Credential Manager is currently available for Windows, macOS, and Linux\*. GCM only works with HTTP(S) remotes; you can still use Git with SSH: -- [Azure DevOps SSH](https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops) -- [GitHub SSH](https://help.github.com/en/articles/connecting-to-github-with-ssh) -- [Bitbucket SSH](https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html) +- [Azure DevOps SSH][azure-devops-ssh] +- [GitHub SSH][github-ssh] +- [Bitbucket SSH][bitbucket-ssh] Feature|Windows|macOS|Linux\* -|:-:|:-:|:-: Installer/uninstaller|✓|✓|✓ -Secure platform credential storage [(see more)](docs/credstores.md)|✓|✓|✓ +Secure platform credential storage [(see more)][gcm-credstores]|✓|✓|✓ Multi-factor authentication support for Azure DevOps|✓|✓|✓ Two-factor authentication support for GitHub|✓|✓|✓ Two-factor authentication support for Bitbucket|✓|✓|✓ @@ -75,7 +75,7 @@ brew uninstall --cask git-credential-manager-core ### macOS Package -We also provide a [.pkg installer](https://github.com/GitCredentialManager/git-credential-manager/releases/latest) with each release. To install, double-click the installation package and follow the instructions presented. +We also provide a [.pkg installer][latest-release] with each release. To install, double-click the installation package and follow the instructions presented. #### Uninstall @@ -95,7 +95,7 @@ sudo /usr/local/share/gcm-core/uninstall.sh #### Ubuntu/Debian distributions -Download the latest [.deb package](https://github.com/GitCredentialManager/git-credential-manager/releases/latest), and run the following: +Download the latest [.deb package][latest-release], and run the following: ```shell sudo dpkg -i @@ -103,7 +103,7 @@ git-credential-manager-core configure ``` **Note:** Although packages were previously offered on certain -[Microsoft Ubuntu package feeds](https://packages.microsoft.com/repos/), +[Microsoft Ubuntu package feeds][ms-package-repos], GCM no longer publishes to these repositories. Please install the Debian package using the above instructions instead. @@ -118,7 +118,7 @@ sudo dpkg -r gcmcore ##### Option 1: Tarball -Download the latest [tarball](https://github.com/GitCredentialManager/git-credential-manager/releases/latest), and run the following: +Download the latest [tarball][latest-release], and run the following: ```shell tar -xvf -C /usr/local/bin @@ -157,21 +157,21 @@ rm $(command -v git-credential-manager-core) To uninstall: -[Follow these instructions](docs/linux-fromsrc-uninstall.md) for your distribution. +[Follow these instructions][linux-uninstall] for your distribution. -**Note:** all Linux distributions [require additional configuration](https://aka.ms/gcm/credstores) to use GCM. +**Note:** all Linux distributions [require additional configuration][gcm-credstores] to use GCM. --- ### Windows -GCM is included with [Git for Windows](https://gitforwindows.org/), and the latest version is included in each new Git for Windows release. This is the preferred way to install GCM on Windows. During installation you will be asked to select a credential helper, with GCM being set as the default. +GCM is included with [Git for Windows][git-for-windows], and the latest version is included in each new Git for Windows release. This is the preferred way to install GCM on Windows. During installation you will be asked to select a credential helper, with GCM being set as the default. -![image](https://user-images.githubusercontent.com/5658207/140082529-1ac133c1-0922-4a24-af03-067e27b3988b.png) +![image][git-for-windows-screenshot] #### Standalone installation -You can also download the [latest installer](https://github.com/GitCredentialManager/git-credential-manager/releases/latest) for Windows to install GCM standalone. +You can also download the [latest installer][latest-release] for Windows to install GCM standalone. **:warning: Important :warning:** @@ -200,10 +200,10 @@ To uninstall, open Control Panel and navigate to the Programs and Features scree #### Windows Subsystem for Linux (WSL) Git Credential Manager can be used with the [Windows Subsystem for Linux -(WSL)](https://aka.ms/wsl) to enable secure authentication of your remote Git +(WSL)][ms-wsl] to enable secure authentication of your remote Git repositories from inside of WSL. -[Please see the GCM on WSL docs](docs/wsl.md) for more information. +[Please see the GCM on WSL docs][gcm-wsl] for more information. ## Supported Git versions @@ -218,50 +218,90 @@ Git that are not compatible. - Git 2.26.2 This version of Git introduced a breaking change with parsing credential - configuration that GCM relies on. This issue was fixed in commit [`12294990`](https://github.com/git/git/commit/12294990c90e043862be9eb7eb22c3784b526340) + configuration that GCM relies on. This issue was fixed in commit [`12294990`][gcm-commit-12294990] of the Git project, and released in Git 2.27.0. ## How to use Once it's installed and configured, Git Credential Manager is called implicitly by Git. You don't have to do anything special, and GCM isn't intended to be called directly by the user. -For example, when pushing (`git push`) to [Azure DevOps](https://dev.azure.com), [Bitbucket](https://bitbucket.org), or [GitHub](https://github.com), a window will automatically open and walk you through the sign-in process. +For example, when pushing (`git push`) to [Azure DevOps][azure-devops], [Bitbucket][bitbucket], or [GitHub][github], a window will automatically open and walk you through the sign-in process. (This process will look slightly different for each Git host, and even in some cases, whether you've connected to an on-premises or cloud-hosted Git host.) Later Git commands in the same repository will re-use existing credentials or tokens that GCM has stored for as long as they're valid. -Read full command line usage [here](docs/usage.md). +Read full command line usage [here][gcm-usage]. ### Configuring a proxy -See detailed information [here](https://aka.ms/gcm/httpproxy). +See detailed information [here][gcm-http-proxy]. ## Additional Resources -- [Frequently asked questions](docs/faq.md) -- [Development and debugging](docs/development.md) -- [Command-line usage](docs/usage.md) -- [Configuration options](docs/configuration.md) -- [Environment variables](docs/environment.md) -- [Enterprise configuration](docs/enterprise-config.md) -- [Network and HTTP configuration](docs/netconfig.md) -- [Credential stores](docs/credstores.md) -- [Architectural overview](docs/architecture.md) -- [Host provider specification](docs/hostprovider.md) -- [Azure Repos OAuth tokens](docs/azrepos-users-and-tokens.md) -- [GitLab support](docs/gitlab.md) +- [Frequently asked questions][gcm-faq] +- [Development and debugging][gcm-dev] +- [Command-line usage][gcm-usage] +- [Configuration options][gcm-config] +- [Environment variables][gcm-env] +- [Enterprise configuration][gcm-enterprise-config] +- [Network and HTTP configuration][gcm-net-config] +- [Credential stores][gcm-credstores] +- [Architectural overview][gcm-arch] +- [Host provider specification][gcm-host-provider] +- [Azure Repos OAuth tokens][gcm-azure-tokens] +- [GitLab support][gcm-gitlab] ## Experimental Features -- [Windows broker (experimental)](docs/windows-broker.md) +- [Windows broker (experimental)][gcm-windows-broker] ## Contributing This project welcomes contributions and suggestions. -See the [contributing guide](CONTRIBUTING.md) to get started. +See the [contributing guide][gcm-contributing] to get started. -This project follows [GitHub's Open Source Code of Conduct](CODE_OF_CONDUCT.md). +This project follows [GitHub's Open Source Code of Conduct][gcm-coc]. ## License -We're [MIT](LICENSE) licensed. -When using GitHub logos, please be sure to follow the [GitHub logo guidelines](https://github.com/logos). +We're [MIT][gcm-license] licensed. +When using GitHub logos, please be sure to follow the [GitHub logo guidelines][github-logos]. + +[azure-devops]: https://dev.azure.com/ +[azure-devops-ssh]: https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops +[bitbucket]: https://bitbucket.org +[bitbucket-ssh]: https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html +[build-status-badge]: https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml/badge.svg +[dotnet]: https://dotnet.microsoft.com +[gcm]: https://github.com/GitCredentialManager/git-credential-manager +[gcm-arch]: docs/architecture.md +[gcm-azure-tokens]: docs/azrepos-users-and-tokens.md +[gcm-coc]: CODE_OF_CONDUCT.md +[gcm-commit-12294990]: https://github.com/git/git/commit/12294990c90e043862be9eb7eb22c3784b526340 +[gcm-config]: docs/configuration.md +[gcm-contributing]: CONTRIBUTING.md +[gcm-credstores]: docs/credstores.md +[gcm-dev]: docs/development.md +[gcm-enterprise-config]: docs/enterprise-config.md +[gcm-env]: docs/environment.md +[gcm-faq]: docs/faq.md +[gcm-for-mac-and-linux]: https://github.com/microsoft/Git-Credential-Manager-for-Mac-and-Linux +[gcm-for-windows]: https://github.com/microsoft/Git-Credential-Manager-for-Windows +[gcm-gitlab]: docs/gitlab.md +[gcm-host-provider]: docs/hostprovider.md +[gcm-http-proxy]: docs/netconfig.md#http-proxy +[gcm-license]: LICENSE +[gcm-net-config]: docs/netconfig.md +[gcm-usage]: docs/usage.md +[gcm-windows-broker]: docs/windows-broker.md +[gcm-wsl]: docs/wsl.md +[git-for-windows]: https://gitforwindows.org/ +[git-for-windows-screenshot]: https://user-images.githubusercontent.com/5658207/140082529-1ac133c1-0922-4a24-af03-067e27b3988b.png +[git-tools-credential-storage]: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage +[github]: https://github.com +[github-ssh]: https://help.github.com/en/articles/connecting-to-github-with-ssh +[github-logos]: https://github.com/logos +[latest-release]: https://github.com/GitCredentialManager/git-credential-manager/releases/latest +[linux-uninstall]: docs/linux-fromsrc-uninstall.md +[ms-package-repos]: https://packages.microsoft.com/repos/ +[ms-wsl]: https://aka.ms/wsl# +[workflow-status]: https://github.com/GitCredentialManager/git-credential-manager/actions/workflows/continuous-integration.yml diff --git a/SECURITY.md b/SECURITY.md index 8785fd5ba..e9a6244a3 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,5 +1,7 @@ # Security -If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty](https://hackerone.com/github) +If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty][hackerone-github] Thanks for helping make GitHub products safe for everyone. + +[hackerone-github]: https://hackerone.com/github diff --git a/docs/architecture.md b/docs/architecture.md index 7790dfc8c..0faf1de10 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -44,7 +44,7 @@ library (C#). The library targets .NET Standard as well as .NET Framework. > **Note** > > The reason for also targeting .NET Framework directly is that the -> `Microsoft.Identity.Client` ([MSAL.NET](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet)) +> `Microsoft.Identity.Client` ([MSAL.NET][msal]) > library requires a .NET Framework target to be able to show the embedded web > browser auth pop-up on Windows platforms. > @@ -52,8 +52,7 @@ library (C#). The library targets .NET Standard as well as .NET Framework. > our own browser pop-up handling code on .NET meaning both Windows and > Mac. We haven't yet gotten around to exploring this. > -> See [this](https://github.com/GitCredentialManager/git-credential-manager/issues/113) -> issue for more information. +> See [GCM issue 113][issue-113] for more information. The entry-point for GCM can be found in the `Git-Credential-Manager` project, a console application that targets both .NET and .NET Framework. @@ -80,9 +79,9 @@ helpers on Windows. ### Cross-platform UI -We hope to be able to migrate the WPF/Windows only helpers to [Avalonia](https://avaloniaui.net/) -in order to gain cross-platform graphical user interface support. See [this](https://github.com/GitCredentialManager/git-credential-manager/issues/136) -issue for up-to-date progress on this effort. +We hope to be able to migrate the WPF/Windows only helpers to [Avalonia][avalonia] +in order to gain cross-platform graphical user interface support. See +[GCM issue 136][issue-136] for up-to-date progress on this effort. ### Microsoft authentication @@ -148,7 +147,7 @@ Git Credential Manager maintains a set of known commands including GCM also maintains a set of known, registered host providers that implement the `IHostProvider` interface. Providers register themselves by adding an instance of the provider to the `Application` object via the `RegisterProvider` -method [in `Core.Program`](../src/shared/Git-Credential-Manager/Program.cs). +method in [`Core.Program`][core-program]. The `GenericHostProvider` is registered last so that it can handle all other HTTP-based remotes as a catch-all, and provide basic username/password auth and detect the presence of Windows Integrated Authentication (Kerberos, NTLM, @@ -162,7 +161,7 @@ The `Get|Store|EraseCommand`s consult the host provider registry for the most appropriate host provider. The default registry implementation select the a host provider by asking each registered provider in turn if they understand the request. The provider selection can be overridden by the user via the -[`credential.provider`](configuration.md#credentialprovider) or [`GCM_PROVIDER`](environment.md#GCM_PROVIDER) +[`credential.provider`][credential-provider] or [`GCM_PROVIDER`][gcm-provider] configuration and environment variable respectively (3). The `Get|Store|EraseCommand`s call the corresponding @@ -277,3 +276,11 @@ operation/authentication. The `ITrace` component can be found on the `ICommandContext` object or passed in directly to some constructors. Verbose and diagnostic information is be written to the trace object in most places of GCM. + +[avalonia]: https://avaloniaui.net/ +[core-program]: ../src/shared/Git-Credential-Manager/Program.cs +[credential-provider]: configuration.md#credentialprovider +[issue-113]: https://github.com/GitCredentialManager/git-credential-manager/issues/113 +[issue-136]: https://github.com/GitCredentialManager/git-credential-manager/issues/136 +[gcm-provider]: environment.md#GCM_PROVIDER +[msal]: https://github.com/AzureAD/microsoft-authentication-library-for-dotnet diff --git a/docs/autodetect.md b/docs/autodetect.md index 398b7598f..954617da1 100644 --- a/docs/autodetect.md +++ b/docs/autodetect.md @@ -18,7 +18,7 @@ In order to detect which host provider to use for a self-hosted instance, each provider can provide some heuristic matching of the hostname. For example any hostname that begins "github.*" will be matched to the GitHub host provider. -If a heuristic matches incorrectly, you can always [explicitly configure](#manual-configuration) +If a heuristic matches incorrectly, you can always [explicitly configure][explicit-config] GCM to use a particular provider. ## Remote URL probing @@ -28,19 +28,19 @@ URL and inspect HTTP response headers to try and detect a self-hosted instance. This network call is only performed if neither an exact nor fuzzy match by hostname can be made. Only one HTTP `HEAD` call is made per credential request -received by Git. To avoid this network call, please [explicitly configure](#explicit-configuration) +received by Git. To avoid this network call, please [explicitly configure][explicit-config] the host provider for your self-hosted instance. After a successful detection of the host provider, GCM will automatically set -the [`credential.provider` configuration entry](configuration.md#credentialprovider) +the [`credential.provider`][credential-provider] configuration entry for that remote to avoid needing to perform this expensive network call in future requests. ### Timeout You can control how long GCM will wait for a response to the remote network call -by setting the [`GCM_AUTODETECT_TIMEOUT`](environment.md#GCM_AUTODETECT_TIMEOUT) -environment variable, or the [`credential.autoDetectTimeout`](configuration.md#credentialautodetecttimeout) +by setting the [`GCM_AUTODETECT_TIMEOUT`][gcm-autodetect-timeout] +environment variable, or the [`credential.autoDetectTimeout`][credential-autoDetectTimeout] Git configuration setting to the maximum number of milliseconds to wait. The default value is 2000 milliseconds (2 seconds). You can prevent the network @@ -52,8 +52,8 @@ If the auto-detection mechanism fails to select the correct host provider, or if the remote probing network call is causing performance issues, you can configure GCM to always use a particular host provider, for a given remote URL. -You can either use the the [`GCM_PROVIDER`](environment.md#GCM_PROVIDER) -environment variable, or the [`credential.provider`](configuration.md#credentialprovider) +You can either use the the [`GCM_PROVIDER`][gcm-provider] +environment variable, or the [`credential.provider`][credential-provider] Git configuration setting for this purpose. For example to tell GCM to always use the GitHub host provider for the @@ -62,3 +62,9 @@ For example to tell GCM to always use the GitHub host provider for the ```shell git config --global credential.ghe.example.com.provider github ``` + +[credential-autoDetectTimeout]: configuration.md#credentialautodetecttimeout +[credential-provider]: configuration.md#credentialprovider +[explicit-config]: #manual-configuration +[gcm-autodetect-timeout]: environment.md#GCM_AUTODETECT_TIMEOUT +[gcm-provider]: environment.md#GCM_PROVIDER diff --git a/docs/azrepos-users-and-tokens.md b/docs/azrepos-users-and-tokens.md index 1aab32262..d11fe168a 100644 --- a/docs/azrepos-users-and-tokens.md +++ b/docs/azrepos-users-and-tokens.md @@ -8,8 +8,8 @@ The Azure Repos host provider supports creating multiple types of credential: - Microsoft identity OAuth tokens To select which type of credential the Azure Repos host provider will create -and use, you can set the [`credential.azreposCredentialType`](configuration.md#credentialazreposcredentialtype) -configuration entry (or [`GCM_AZREPOS_CREDENTIALTYPE`](environment.md#GCM_AZREPOS_CREDENTIALTYPE) +and use, you can set the [`credential.azreposCredentialType`][credential-azreposCredentialType] +configuration entry (or [`GCM_AZREPOS_CREDENTIALTYPE`][gcm-azrepos-credential-type] environment variable). ### Azure DevOps personal access tokens @@ -18,7 +18,7 @@ Historically, the only option supported by the Azure Repos host provider was Azure DevOps Personal Access Tokens (PATs). These PATs are only used by Azure DevOps, and must be [managed through the Azure -DevOps user settings page](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page) or [REST API](https://docs.microsoft.com/en-gb/rest/api/azure/devops/tokens/pats). +DevOps user settings page][azure-devops-pats] or [REST API][azure-devops-api]. PATs have a limited lifetime and new tokens must be created once they expire. In Git Credential Manager, when a PAT expired (or was manually revoked) this @@ -188,8 +188,7 @@ inherited). To associate a user account with a particular Git remote you must manually edit the remote URL using `git config` commands to include the username in the -[user information](https://tools.ietf.org/html/rfc3986#section-3.2.1) part of -the URL. +[user information][rfc3986-s321] part of the URL. ```shell git config --local remote.origin.url https://alice-alt%40contoso.com@contoso.visualstudio.com/project/_git/repo @@ -218,3 +217,9 @@ contoso: fabrikam: (global) -> alice@fabrikam.com ``` + +[azure-devops-pats]: https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=preview-page +[credential-azreposCredentialType]: configuration.md#credentialazreposcredentialtype +[gcm-azrepos-credential-type]: environment.md#GCM_AZREPOS_CREDENTIALTYPE +[azure-devops-api]: https://docs.microsoft.com/en-gb/rest/api/azure/devops/tokens/pats +[rfc3986-s321]: https://tools.ietf.org/html/rfc3986#section-3.2.1 diff --git a/docs/bitbucket-development.md b/docs/bitbucket-development.md index dc7140770..e9cef3b56 100644 --- a/docs/bitbucket-development.md +++ b/docs/bitbucket-development.md @@ -7,15 +7,15 @@ Additionally Bitbucket supports App-specific passwords which can be used via Bas To enhance security Bitbucket offers optional Two-Factor Authentication (2FA). When 2FA is enabled username/password Basic Auth access to the REST APIs and to Git repositories is suspended. At that point users are left with the choice of username/apps-specific-password Basic Auth for REST APIs and Git interactions, OAuth for REST APIs and Git/Hg interactions or SSH for Git/HG interactions and one of the previous choices for REST APIs. SSH and REST API access are beyond the scope of this document. -Read about [Bitbucket's 2FA implementation](https://confluence.atlassian.com/bitbucket/two-step-verification-777023203.html). +Read about [Bitbucket's 2FA implementation][2fa-impl]. App-specific passwords are not particularly user friendly as once created Bitbucket hides their value, even from the owner. They are intended for use within application that talk to Bitbucket where application can remember and use the app-specific-password. -[Additional information](https://confluence.atlassian.com/display/BITBUCKET/App+passwords). +[Additional information][additional-info]. OAuth is the intended authentication method for user interactions with HTTPS remote URL for Git repositories when 2FA is active. Essentially once a client application has an OAuth access token it can be used in place of a user's password. -Read more about information [Bitbucket's OAuth implementation](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html). +Read more about information [Bitbucket's OAuth implementation][oauth-impl]. Bitbucket's OAuth implementation follows the standard specifications for OAuth 2.0, which is out of scope for this document. However it implements a comparatively rare part of OAuth 2.0 Refresh Tokens. @@ -30,7 +30,7 @@ This is explained in more detail below. ## Multiple User Accounts -Unlike the GitHub implementation within the Git Credential Manager, the Bitbucket implementation stores 'secrets', passwords, app-specific passwords, or OAuth tokens, with usernames in the [Windows Credential Manager](https://msdn.microsoft.com/en-us/library/windows/desktop/aa374792(v=vs.85).aspx) vault. +Unlike the GitHub implementation within the Git Credential Manager, the Bitbucket implementation stores 'secrets', passwords, app-specific passwords, or OAuth tokens, with usernames in the [Windows Credential Manager][wincred-manager] vault. Depending on the circumstances this means either saving an explicit username in to the Windows Credential Manager/Vault or including the username in the URL used as the identifying key of entries in the Windows Credential Manager vault, i.e. using a key such as `git:https://mminns@bitbucket.org/` rather than `git:https://bitbucket.org`. This means that the Bitbucket implementation in the GCM can support multiple accounts, and usernames, for a single user against Bitbucket, e.g. a personal account and a work account. @@ -65,7 +65,7 @@ The Access and Refresh Tokens will be stored against the username and the userna ## On-Premise Bitbucket -On-premise Bitbucket, more correctly known as Bitbucket Server or Bitbucket DC, has a number of differences compared to the cloud instance of Bitbucket, [bitbucket.org](https://bitbucket.org). +On-premise Bitbucket, more correctly known as Bitbucket Server or Bitbucket DC, has a number of differences compared to the cloud instance of Bitbucket, [bitbucket.org][bitbucket]. As far as GCMC is concerned the main difference it doesn't support OAuth so only Basic Authentication is available. @@ -73,10 +73,18 @@ It is possible to test with Bitbucket Server by running it locally using the fol ❯ atlas-run-standalone --product bitbucket -See the developer documentation for [atlas-run-standalone](https://developer.atlassian.com/server/framework/atlassian-sdk/atlas-run-standalone/). +See the developer documentation for [atlas-run-standalone][atlas-run-standalone]. This will download and run a standalone instance of Bitbucket Server which can be accessed using the credentials `admin`/`admin` at https://localhost:7990/bitbucket -Atlassian has [documentation](https://developer.atlassian.com/server/framework/atlassian-sdk/) on how to download and install their SDK. +Atlassian has [documentation][atlassian-sdk] on how to download and install their SDK. + +[additional-info]:https://confluence.atlassian.com/display/BITBUCKET/App+passwords +[atlas-run-standalone]: https://developer.atlassian.com/server/framework/atlassian-sdk/atlas-run-standalone/ +[bitbucket]: https://bitbucket.org +[2fa-impl]: https://confluence.atlassian.com/bitbucket/two-step-verification-777023203.html +[oauth-impl]: https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html +[atlassian-sdk]: https://developer.atlassian.com/server/framework/atlassian-sdk/ +[wincred-manager]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa374792(v=vs.85).aspx diff --git a/docs/configuration.md b/docs/configuration.md index e295c68d7..94393c3ea 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,6 +1,6 @@ # Configuration options -[Git Credential Manager](usage.md) works out of the box for most users. +[Git Credential Manager][usage] works out of the box for most users. Git Credential Manager (GCM) can be configured using Git's configuration files, and follows all of the same rules Git does when consuming the files. @@ -9,7 +9,7 @@ Global configuration settings override system configuration settings, and local GCM honors several levels of settings, in addition to the standard local \> global \> system tiering Git uses. URL-specific settings or overrides can be applied to any value in the `credential` namespace with the syntax below. -Additionally, GCM respects several GCM-specific [environment variables](environment.md) **which take precedence over configuration options**. System administrators may also configure [default values](enterprise-config.md) for many settings used by GCM. +Additionally, GCM respects several GCM-specific [environment variables][envars] **which take precedence over configuration options**. System administrators may also configure [default values][enterprise-config] for many settings used by GCM. GCM will only be used by Git if it is installed and configured. Use `git config --global credential.helper manager-core` to assign GCM as your credential helper. Use `git config credential.helper` to see the current configuration. @@ -50,7 +50,7 @@ git config --global credential.interactive false Defaults to enabled. -**Also see: [GCM_INTERACTIVE](environment.md#GCM_INTERACTIVE)** +**Also see: [GCM_INTERACTIVE][gcm-interactive]** --- @@ -60,7 +60,7 @@ Define the host provider to use when authenticating. ID|Provider -|- -`auto` _(default)_|_\[automatic\]_ ([learn more](autodetect.md)) +`auto` _(default)_|_\[automatic\]_ ([learn more][autodetect]) `azure-repos`|Azure Repos `github`|GitHub `bitbucket`|Bitbucket @@ -77,7 +77,7 @@ This setting is typically used with a scoped URL to map a particular set of remo git config --global credential.ghe.contoso.com.provider github ``` -**Also see: [GCM_PROVIDER](environment.md#GCM_PROVIDER)** +**Also see: [GCM_PROVIDER][gcm-provider]** --- @@ -85,7 +85,7 @@ git config --global credential.ghe.contoso.com.provider github > This setting is deprecated and should be replaced by `credential.provider` with the corresponding provider ID value. > -> Click [here](https://aka.ms/gcm/authority) for more information. +> See the [migration guide][provider-migrate] for more information. Select the host provider to use when authenticating by which authority is supported by the providers. @@ -104,7 +104,7 @@ Authority|Provider(s) git config --global credential.ghe.contoso.com.authority github ``` -**Also see: [GCM_AUTHORITY](environment.md#GCM_AUTHORITY-deprecated)** +**Also see: [GCM_AUTHORITY][gcm-authority]** --- @@ -113,7 +113,7 @@ git config --global credential.ghe.contoso.com.authority github Permit or disable GCM from presenting GUI prompts. If an equivalent terminal/ text-based prompt is available, that will be shown instead. -To disable all interactivity see [credential.interactive](#credentialinteractive). +To disable all interactivity see [credential.interactive][credential-interactive]. #### Example @@ -123,7 +123,7 @@ git config --global credential.guiPrompt false Defaults to enabled. -**Also see: [GCM_GUI_PROMPT](environment.md#GCM_GUI_PROMPT)** +**Also see: [GCM_GUI_PROMPT][gcm-gui-prompt]** --- @@ -132,7 +132,7 @@ Defaults to enabled. Set the maximum length of time, in milliseconds, that GCM should wait for a network response during host provider auto-detection probing. -See [here](autodetect.md) for more information. +See [auto-detection][auto-detection] for more information. **Note:** Use a negative or zero value to disable probing altogether. @@ -144,7 +144,7 @@ Defaults to 2000 milliseconds (2 seconds). git config --global credential.autoDetectTimeout -1 ``` -**Also see: [GCM_AUTODETECT_TIMEOUT](environment.md#GCM_AUTODETECT_TIMEOUT)** +**Also see: [GCM_AUTODETECT_TIMEOUT][gcm-autodetect-timeout]** --- @@ -167,15 +167,15 @@ Value|WIA detection git config --global credential.tfsonprem123.allowWindowsAuth false ``` -**Also see: [GCM_ALLOW_WINDOWSAUTH](environment.md#GCM_ALLOW_WINDOWSAUTH)** +**Also see: [GCM_ALLOW_WINDOWSAUTH][gcm-allow-windowsauth]** --- ### credential.httpProxy _(deprecated)_ -> This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy). +> This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option][git-config-http-proxy]. > -> Click [here](https://aka.ms/gcm/httpproxy) for more information. +> See [HTTP Proxy][http-proxy] for more information. Configure GCM to use the a proxy for network operations. @@ -187,7 +187,7 @@ Configure GCM to use the a proxy for network operations. git config --global credential.httpsProxy http://john.doe:password@proxy.contoso.com ``` -**Also see: [GCM_HTTP_PROXY](environment.md#GCM_HTTP_PROXY-deprecated)** +**Also see: [GCM_HTTP_PROXY][gcm-http-proxy]** --- @@ -212,7 +212,7 @@ _(unset)_|Automatically detect modes git config --global credential.bitbucketAuthModes "oauth,basic" ``` -**Also see: [GCM_BITBUCKET_AUTHMODES](environment.md#GCM_BITBUCKET_AUTHMODES)** +**Also see: [GCM_BITBUCKET_AUTHMODES][gcm-bitbucket-authmodes]** --- @@ -239,7 +239,7 @@ git config --global credential.bitbucketAlwaysRefreshCredentials 1 Defaults to false/disabled. -**Also see: [GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS](environment.md#GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS)** +**Also see: [GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS][gcm-bitbucket-always-refresh-credentials]** --- @@ -265,7 +265,7 @@ _(unset)_|Automatically detect modes git config --global credential.gitHubAuthModes "oauth,basic" ``` -**Also see: [GCM_GITHUB_AUTHMODES](environment.md#GCM_GITHUB_AUTHMODES)** +**Also see: [GCM_GITHUB_AUTHMODES][gcm-github-authmodes]** --- @@ -289,7 +289,7 @@ _(unset)_|Automatically detect modes git config --global credential.gitLabAuthModes "browser" ``` -**Also see: [GCM_GITLAB_AUTHMODES](environment.md#GCM_GITLAB_AUTHMODES)** +**Also see: [GCM_GITLAB_AUTHMODES][gcm-gitlab-authmodes]** --- @@ -306,7 +306,7 @@ Defaults to the value `git`. git config --global credential.namespace "my-namespace" ``` -**Also see: [GCM_NAMESPACE](environment.md#GCM_NAMESPACE)** +**Also see: [GCM_NAMESPACE][gcm-namespace]** --- @@ -316,18 +316,18 @@ Select the type of credential store to use on supported platforms. Default value on Windows is `wincredman`, on macOS is `keychain`, and is unset on Linux. -**Note:** See more information about configuring secret stores [here](credstores.md). +**Note:** See more information about configuring secret stores in [cred-stores][cred-stores]. Value|Credential Store|Platforms -|-|- _(unset)_|Windows: `wincredman`, macOS: `keychain`, Linux: _(none)_|- `wincredman`|Windows Credential Manager (not available over SSH).|Windows -`dpapi`|DPAPI protected files. Customize the DPAPI store location with [credential.dpapiStorePath](#credentialdpapistorepath)|Windows +`dpapi`|DPAPI protected files. Customize the DPAPI store location with [credential.dpapiStorePath][credential-dpapistorepath]|Windows `keychain`|macOS Keychain.|macOS -`secretservice`|[freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/) via [libsecret](https://wiki.gnome.org/Projects/Libsecret) (requires a graphical interface to unlock secret collections).|Linux -`gpg`|Use GPG to store encrypted files that are compatible with the [`pass` utility](https://www.passwordstore.org/) (requires GPG and `pass` to initialize the store).|macOS, Linux -`cache`|Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache).|Windows, macOS, Linux -`plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`credential.plaintextStorePath`](#credentialplaintextstorepath).|Windows, macOS, Linux +`secretservice`|[freedesktop.org Secret Service API][freedesktop-ss] via [libsecret][libsecret] (requires a graphical interface to unlock secret collections).|Linux +`gpg`|Use GPG to store encrypted files that are compatible with the [pass][pass] (requires GPG and `pass` to initialize the store).|macOS, Linux +`cache`|Git's built-in [credential cache][credential-cache].|Windows, macOS, Linux +`plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`credential.plaintextStorePath`][credential-plaintextstorepath].|Windows, macOS, Linux #### Example @@ -335,15 +335,14 @@ _(unset)_|Windows: `wincredman`, macOS: `keychain`, Linux: _(none)_|- git config --global credential.credentialStore gpg ``` -**Also see: [GCM_CREDENTIAL_STORE](environment.md#GCM_CREDENTIAL_STORE)** +**Also see: [GCM_CREDENTIAL_STORE][gcm-credential-store]** --- ### credential.cacheOptions -Pass [options](https://git-scm.com/docs/git-credential-cache#_options) -to the Git credential cache when -[`credential.credentialStore`](#credentialcredentialstore) +Pass [options][cache-options] to the Git credential cache when +[`credential.credentialStore`][credential-credentialstore] is set to `cache`. This allows you to select a different amount of time to cache credentials (the default is 900 seconds) by passing `"--timeout "`. Use of other options like `--socket` is untested @@ -357,13 +356,13 @@ Defaults to empty. git config --global credential.cacheOptions "--timeout 300" ``` -**Also see: [GCM_CREDENTIAL_CACHE_OPTIONS](environment.md#GCM_CREDENTIAL_CACHE_OPTIONS)** +**Also see: [GCM_CREDENTIAL_CACHE_OPTIONS][gcm-credential-cache-options]** --- ### credential.plaintextStorePath -Specify a custom directory to store plaintext credential files in when [`credential.credentialStore`](#credentialcredentialstore) is set to `plaintext`. +Specify a custom directory to store plaintext credential files in when [`credential.credentialStore`][credential-credentialstore] is set to `plaintext`. Defaults to the value `~/.gcm/store` or `%USERPROFILE%\.gcm\store`. @@ -373,13 +372,13 @@ Defaults to the value `~/.gcm/store` or `%USERPROFILE%\.gcm\store`. git config --global credential.plaintextStorePath /mnt/external-drive/credentials ``` -**Also see: [GCM_PLAINTEXT_STORE_PATH](environment.md#GCM_PLAINTEXT_STORE_PATH)** +**Also see: [GCM_PLAINTEXT_STORE_PATH][gcm-plaintext-store-path]** --- ### credential.dpapiStorePath -Specify a custom directory to store DPAPI protected credential files in when [`credential.credentialStore`](#credentialcredentialstore) is set to `dpapi`. +Specify a custom directory to store DPAPI protected credential files in when [`credential.credentialStore`][credential-credentialstore] is set to `dpapi`. Defaults to the value `%USERPROFILE%\.gcm\dpapi_store`. @@ -389,7 +388,7 @@ Defaults to the value `%USERPROFILE%\.gcm\dpapi_store`. git config --global credential.dpapiStorePath D:\credentials ``` -**Also see: [GCM_DPAPI_STORE_PATH](environment.md#GCM_DPAPI_STORE_PATH)** +**Also see: [GCM_DPAPI_STORE_PATH][gcm-dpapi-store-path]** --- @@ -399,7 +398,7 @@ Specify which authentication flow should be used when performing Microsoft authe Defaults to `auto`. -**Note:** If [`credential.msauthUseBroker`](#credentialmsauthusebroker-experimental) is set +**Note:** If [`credential.msauthUseBroker`][credential-msauthusebroker] is set to `true` and the operating system authentication broker is available, all flows will be delegated to the broker. If both of those things are true, then the value of `credential.msauthFlow` has no effect. @@ -417,7 +416,7 @@ Value|Authentication Flow git config --global credential.msauthFlow devicecode ``` -**Also see: [GCM_MSAUTH_FLOW](environment.md#GCM_MSAUTH_FLOW)** +**Also see: [GCM_MSAUTH_FLOW][gcm-msauth-flow]** --- @@ -427,7 +426,7 @@ Use the operating system account manager where available. Defaults to `false`. This default is subject to change in the future. -_**Note:** before you enable this option on Windows, please [review the details](windows-broker.md) about what this means to your local Windows user account._ +_**Note:** before you enable this option on Windows, please review the [Windows Broker][wam] details for what this means to your local Windows user account._ Value|Description -|- @@ -440,13 +439,13 @@ Value|Description git config --global credential.msauthUseBroker true ``` -**Also see: [GCM_MSAUTH_USEBROKER](environment.md#GCM_MSAUTH_USEBROKER-experimental)** +**Also see: [GCM_MSAUTH_USEBROKER][gcm-msauth-usebroker]** --- ### credential.useHttpPath -Tells Git to pass the entire repository URL, rather than just the hostname, when calling out to a credential provider. (This setting [comes from Git itself](https://git-scm.com/docs/gitcredentials/#Documentation/gitcredentials.txt-useHttpPath), not GCM.) +Tells Git to pass the entire repository URL, rather than just the hostname, when calling out to a credential provider. (This setting [comes from Git itself][use-http-path], not GCM.) Defaults to `false`. @@ -520,7 +519,7 @@ Value|Description `pat` _(default)_|Azure DevOps personal access tokens `oauth`|Microsoft identity OAuth tokens (AAD or MSA tokens) -More information about Azure Access tokens can be found [here](azrepos-users-and-tokens.md). +Here is more information about [Azure Access tokens][azure-tokens]. #### Example @@ -528,4 +527,46 @@ More information about Azure Access tokens can be found [here](azrepos-users-and git config --global credential.azreposCredentialType oauth ``` -**Also see: [GCM_AZREPOS_CREDENTIALTYPE](environment.md#GCM_AZREPOS_CREDENTIALTYPE)** +**Also see: [GCM_AZREPOS_CREDENTIALTYPE][gcm-azrepos-credentialtype]** + +[auto-detection]: autodetect.md +[azure-tokens]: azrepos-users-and-tokens.md +[use-http-path]: https://git-scm.com/docs/gitcredentials/#Documentation/gitcredentials.txt-useHttpPath +[credential-credentialstore]: #credentialcredentialstore +[credential-dpapistorepath]: #credentialdpapistorepath +[credential-interactive]: #credentialinteractive +[credential-msauthusebroker]: #credentialmsauthusebroker-experimental +[credential-plaintextstorepath]: #credentialplaintextstorepath +[credential-cache]: https://git-scm.com/docs/git-credential-cache +[cred-stores]: credstores.md +[enterprise-config]: enterprise-config.md +[envars]: environment.md +[freedesktop-ss]: https://specifications.freedesktop.org/secret-service/ +[gcm-allow-windowsauth]: environment.md#GCM_ALLOW_WINDOWSAUTH +[gcm-authority]: environment.md#GCM_AUTHORITY-deprecated +[gcm-autodetect-timeout]: environment.md#GCM_AUTODETECT_TIMEOUT +[gcm-azrepos-credentialtype]: environment.md#GCM_AZREPOS_CREDENTIALTYPE +[gcm-bitbucket-always-refresh-credentials]: environment.md#GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS +[gcm-bitbucket-authmodes]: environment.md#GCM_BITBUCKET_AUTHMODES +[gcm-credential-cache-options]: environment.md#GCM_CREDENTIAL_CACHE_OPTIONS +[gcm-credential-store]: environment.md#GCM_CREDENTIAL_STORE +[gcm-dpapi-store-path]: environment.md#GCM_DPAPI_STORE_PATH +[gcm-github-authmodes]: environment.md#GCM_GITHUB_AUTHMODES +[gcm-gitlab-authmodes]:environment.md#GCM_GITLAB_AUTHMODES +[gcm-gui-prompt]: environment.md#GCM_GUI_PROMPT +[gcm-http-proxy]: environment.md#GCM_HTTP_PROXY-deprecated +[gcm-interactive]: environment.md#GCM_INTERACTIVE +[gcm-msauth-flow]: environment.md#GCM_MSAUTH_FLOW +[gcm-msauth-usebroker]: environment.md#GCM_MSAUTH_USEBROKER-experimental +[gcm-namespace]: environment.md#GCM_NAMESPACE +[gcm-plaintext-store-path]: environment.md#GCM_PLAINTEXT_STORE_PATH +[gcm-provider]: environment.md#GCM_PROVIDER +[usage]: usage.md +[git-config-http-proxy]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy +[http-proxy]: netconfig.md#http-proxy +[autodetect]: autodetect.md +[libsecret]: https://wiki.gnome.org/Projects/Libsecret +[provider-migrate]: migration.md#gcm_authority +[cache-options]: https://git-scm.com/docs/git-credential-cache#_options +[pass]: https://www.passwordstore.org/ +[wam]: windows-broker.md diff --git a/docs/credstores.md b/docs/credstores.md index bb206e647..157eaf930 100644 --- a/docs/credstores.md +++ b/docs/credstores.md @@ -5,9 +5,9 @@ There are several options for storing credentials that GCM supports: - Windows Credential Manager - DPAPI protected files - macOS Keychain -- [freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/) -- GPG/[`pass`](https://www.passwordstore.org/) compatible files -- Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache) +- [freedesktop.org Secret Service API][freedesktop-secret-service] +- GPG/[`pass`][passwordstore] compatible files +- Git's built-in [credential cache][credential-cache] - Plaintext files The default credential stores on macOS and Windows are the macOS Keychain and @@ -15,8 +15,8 @@ the Windows Credential Manager, respectively. GCM comes without a default store on Linux distributions. -You can select which credential store to use by setting the [`GCM_CREDENTIAL_STORE`](environment.md#GCM_CREDENTIAL_STORE) -environment variable, or the [`credential.credentialStore`](configuration.md#credentialcredentialstore) +You can select which credential store to use by setting the [`GCM_CREDENTIAL_STORE`][gcm-credential-store] +environment variable, or the [`credential.credentialStore`][credential-store] Git configuration setting. For example: ```shell @@ -49,8 +49,8 @@ This credential store uses the Windows Credential APIs (`wincred.h`) to store data securely in the Windows Credential Manager (also known as the Windows Credential Vault in earlier versions of Windows). -You can [access and manage data in the credential manager](https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0) -from the control panel, or via the [`cmdkey` command-line tool](https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/cmdkey). +You can [access and manage data in the credential manager][access-windows-credential-manager] +from the control panel, or via the [`cmdkey` command-line tool][cmdkey]. When connecting to a Windows machine over a network session (such as SSH), GCM is unable to persist credentials to the Windows Credential Manager due to @@ -73,7 +73,7 @@ git config --global credential.credentialStore dpapi This credential store uses Windows DPAPI to encrypt credentials which are stored as files in your file system. The file structure is the same as the -[plaintext files credential store](#plaintext-files) except the first line (the +[plaintext files credential store][plaintext-files] except the first line (the secret value) is protected by DPAPI. By default files are stored in `%USERPROFILE%\.gcm\dpapi_store`. This can be @@ -97,10 +97,10 @@ git config --global credential.credentialStore keychain This credential store uses the default macOS Keychain, which is typically the `login` keychain. -You can [manage data stored in the keychain](https://support.apple.com/en-gb/guide/mac-help/mchlf375f392/mac) +You can [manage data stored in the keychain][mac-keychain-management] using the Keychain Access application. -## [freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/) +## [freedesktop.org Secret Service API][freedesktop-secret-service] **Available on:** _Linux_ @@ -119,7 +119,7 @@ tools such as `secret-tool` and `seahorse`. A graphical user interface is required in order to show a secure prompt to request a secret collection be unlocked. -## GPG/[`pass`](https://www.passwordstore.org/) compatible files +## GPG/[`pass`][passwordstore] compatible files **Available on:** _macOS, Linux_ @@ -133,7 +133,7 @@ git config --global credential.credentialStore gpg This credential store uses GPG to encrypt files containing credentials which are stored in your file system. The file structure is compatible with the popular -[`pass`](https://www.passwordstore.org/) tool. By default files are stored in +[`pass`][passwordstore] tool. By default files are stored in `~/.password-store` but this can be configured using the `pass` environment variable `PASSWORD_STORE_DIR`. @@ -176,7 +176,7 @@ export GPG_TTY=$(tty) **Note:** Using `/dev/tty` does not appear to work here - you must use the real TTY device path, as returned by the `tty` utility. -## Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache) +## Git's built-in [credential cache][credential-cache] **Available on:** _macOS, Linux_ @@ -187,17 +187,16 @@ git config --global credential.credentialStore cache ``` This credential store uses Git's built-in ephemeral -[in-memory credential cache](https://git-scm.com/docs/git-credential-cache). +in-memory [credential cache][credential-cache]. This helps you reduce the number of times you have to authenticate but doesn't require storing credentials on persistent storage. It's good for -scenarios like [Azure Cloud Shell](https://docs.microsoft.com/azure/cloud-shell/overview) -or [AWS CloudShell](https://aws.amazon.com/cloudshell/), where you don't want to +scenarios like [Azure Cloud Shell][azure-cloudshell] +or [AWS CloudShell][aws-cloudshell], where you don't want to leave credentials on disk but also don't want to re-authenticate on every Git operation. By default, `git credential-cache` stores your credentials for 900 seconds. -That, and any other -[options it accepts](https://git-scm.com/docs/git-credential-cache#_options), +That, and any other [options it accepts][git-credential-cache-options], may be altered by setting them in the environment variable `GCM_CREDENTIAL_CACHE_OPTIONS` or the Git config value `credential.cacheOptions`. (Using the `--socket` option is untested @@ -232,7 +231,8 @@ On POSIX platforms the newly created store directory will have permissions set such that only the owner can `r`ead/`w`rite/e`x`ecute (`700` or `drwx---`). Permissions on existing directories will not be modified. -NB. GCM's plaintext store is distinct from [git-credential-store](https://git-scm.com/docs/git-credential-store), though the formats are similar. The default paths differ. +NB. GCM's plaintext store is distinct from [git-credential-store][git-credential-store], +though the formats are similar. The default paths differ. --- @@ -251,4 +251,16 @@ permissions on this directory such that no other users or applications can access files within. If possible, use a path that exists on an external volume that you take with you and use full-disk encryption. ---- +[access-windows-credential-manager]: https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0 +[aws-cloudshell]: https://aws.amazon.com/cloudshell/ +[azure-cloudshell]: https://docs.microsoft.com/azure/cloud-shell/overview +[cmdkey]: https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/cmdkey +[credential-store]: configuration.md#credentialcredentialstore +[credential-cache]: https://git-scm.com/docs/git-credential-cache +[freedesktop-secret-service]: https://specifications.freedesktop.org/secret-service/ +[gcm-credential-store]: environment.md#GCM_CREDENTIAL_STORE +[git-credential-store]: https://git-scm.com/docs/git-credential-store +[mac-keychain-management]: https://support.apple.com/en-gb/guide/mac-help/mchlf375f392/mac +[git-credential-cache-options]: https://git-scm.com/docs/git-credential-cache#_options +[passwordstore]: https://www.passwordstore.org/ +[plaintext-files]: #plaintext-files diff --git a/docs/development.md b/docs/development.md index fdec0d8b7..a8f88997a 100644 --- a/docs/development.md +++ b/docs/development.md @@ -6,7 +6,7 @@ Start by cloning this repository: git clone https://github.com/GitCredentialManager/git-credential-manager ``` -You also need the latest version of the .NET SDK which can be downloaded and installed from [here](https://dotnet.microsoft.com/). +You also need the latest version of the .NET SDK which can be downloaded and installed from the [.NET website][dotnet-web]. ## Building @@ -58,7 +58,7 @@ The flat binaries can also be found in `out/linux/Packaging.Linux/payload/Debug` To debug from inside an IDE you'll want to set `Git-Credential-Manager` as the startup project, and specify one of `get`, `store`, or `erase` as a program argument. -To simulate Git interacting with GCM, when you start from your IDE of choice, you'll need to enter the following [information over standard input](https://git-scm.com/docs/git-credential#IOFMT): +To simulate Git interacting with GCM, when you start from your IDE of choice, you'll need to enter the following [information over standard input][ioformat]: ```text protocol=http @@ -76,7 +76,7 @@ username= password= ``` -For more information about how Git interacts with credential helpers, please read Git's [documentation](https://git-scm.com/docs/gitcredentials#_custom_helpers). +For more information about how Git interacts with credential helpers, please read Git's documentation on [custom helpers][custom-helpers]. ### Attaching to a running process @@ -133,3 +133,7 @@ or ```console report coverage - win ``` + +[dotnet-web]: https://dotnet.microsoft.com/ +[custom-helpers]: https://git-scm.com/docs/gitcredentials#_custom_helpers +[ioformat]: https://git-scm.com/docs/git-credential#IOFMT diff --git a/docs/enterprise-config.md b/docs/enterprise-config.md index 96ce891d5..bfdc7e302 100644 --- a/docs/enterprise-config.md +++ b/docs/enterprise-config.md @@ -3,8 +3,8 @@ Git Credential Manager (GCM) can be configured using multiple different mechanisms. In order of preference, those mechanisms are: -1. [Environment variables](environment.md) -1. [Standard Git configuration files](configuration.md) +1. [Environment variables][environment] +1. Standard [Git configuration][config] files 1. Repository/local configuration (`.git/config`) 1. User/global configuration (`$HOME/.gitconfig` or `%HOME%\.gitconfig`) 1. Installation/system configuration (`etc/gitconfig`) @@ -50,7 +50,7 @@ By using the Windows Registry, system administrators can use Group Policy to easily set defaults for GCM's settings. The names and possible values of all settings under this key are the same as -those of the [Git configuration](configuration.md) settings. +those of the [Git configuration][config] settings. The type of each registry key can be either `REG_SZ` (string) or `REG_DWORD` (integer). @@ -58,3 +58,6 @@ The type of each registry key can be either `REG_SZ` (string) or `REG_DWORD` ## macOS/Linux Default configuration setting stores has not been implemented. + +[environment]: environment.md +[config]: configuration.md diff --git a/docs/environment.md b/docs/environment.md index 18cfa4774..36372640c 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -1,8 +1,8 @@ # Environment variables -[Git Credential Manager](usage.md) works out of the box for most users. Configuration options are available to customize or tweak behavior. +[Git Credential Manager][gcm] works out of the box for most users. Configuration options are available to customize or tweak behavior. -Git Credential Manager (GCM) can be configured using environment variables. **Environment variables take precedence over [configuration](configuration.md) options and enterprise system administrator [default values](enterprise-config.md)**. +Git Credential Manager (GCM) can be configured using environment variables. **Environment variables take precedence over [configuration][configuration] options and enterprise system administrator [default values][default-values]**. For the complete list of environment variables GCM understands, see the list below. @@ -156,7 +156,7 @@ export GCM_INTERACTIVE=0 Defaults to enabled. -**Also see: [credential.interactive](configuration.md#credentialinteractive)** +**Also see: [credential.interactive][credential-interactive]** --- @@ -166,7 +166,7 @@ Define the host provider to use when authenticating. ID|Provider -|- -`auto` _(default)_|_\[automatic\]_ ([learn more](autodetect.md)) +`auto` _(default)_|_\[automatic\]_ ([learn more][autodetect]) `azure-repos`|Azure Repos `github`|GitHub `gitlab`|GitLab _(supports OAuth in browser, personal access token and Basic Authentication)_ @@ -190,7 +190,7 @@ SET GCM_PROVIDER=github export GCM_PROVIDER=github ``` -**Also see: [credential.provider](configuration.md#credentialprovider)** +**Also see: [credential.provider][credential-provider]** --- @@ -198,7 +198,7 @@ export GCM_PROVIDER=github > This setting is deprecated and should be replaced by `GCM_PROVIDER` with the corresponding provider ID value. > -> Click [here](https://aka.ms/gcm/authority) for more information. +> See the [migration guide][migration-guide] for more information. Select the host provider to use when authenticating by which authority is supported by the providers. @@ -224,7 +224,7 @@ SET GCM_AUTHORITY=github export GCM_AUTHORITY=github ``` -**Also see: [credential.authority](configuration.md#credentialauthority-deprecated)** +**Also see: [credential.authority][credential-authority]** --- @@ -233,7 +233,7 @@ export GCM_AUTHORITY=github Permit or disable GCM from presenting GUI prompts. If an equivalent terminal/ text-based prompt is available, that will be shown instead. -To disable all interactivity see [GCM_INTERACTIVE](#gcm_interactive). +To disable all interactivity see [GCM_INTERACTIVE][gcm-interactive]. #### Example @@ -251,7 +251,7 @@ export GCM_GUI_PROMPT=0 Defaults to enabled. -**Also see: [credential.guiPrompt](configuration.md#credentialguiprompt)** +**Also see: [credential.guiPrompt][credential-guiprompt]** --- @@ -260,7 +260,7 @@ Defaults to enabled. Set the maximum length of time, in milliseconds, that GCM should wait for a network response during host provider auto-detection probing. -See [here](autodetect.md) for more information. +See [autodetection][autodetect] for more information. **Note:** Use a negative or zero value to disable probing altogether. @@ -280,7 +280,7 @@ SET GCM_AUTODETECT_TIMEOUT=-1 export GCM_AUTODETECT_TIMEOUT=-1 ``` -**Also see: [credential.autoDetectTimeout](configuration.md#credentialautodetecttimeout)** +**Also see: [credential.autoDetectTimeout][credential-autodetecttimeout]** --- @@ -311,15 +311,15 @@ SET GCM_ALLOW_WINDOWSAUTH=0 export GCM_ALLOW_WINDOWSAUTH=0 ``` -**Also see: [credential.allowWindowsAuth](environment.md#credentialallowWindowsAuth)** +**Also see: [credential.allowWindowsAuth][credential-allowwindowsauth]** --- ### GCM_HTTP_PROXY _(deprecated)_ -> This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy). +> This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option][git-httpproxy]. > -> Click [here](https://aka.ms/gcm/httpproxy) for more information. +> See the [HTTP proxy configuration][network-http-proxy] for more information. Configure GCM to use the a proxy for network operations. @@ -337,7 +337,7 @@ SET GCM_HTTP_PROXY=http://john.doe:password@proxy.contoso.com export GCM_HTTP_PROXY=http://john.doe:password@proxy.contoso.com ``` -**Also see: [credential.httpProxy](configuration.md#credentialhttpProxy-deprecated)** +**Also see: [credential.httpProxy][credential-httpproxy]** --- @@ -368,7 +368,7 @@ SET GCM_BITBUCKET_AUTHMODES="oauth,basic" export GCM_BITBUCKET_AUTHMODES="oauth,basic" ``` -**Also see: [credential.bitbucketAuthModes](configuration.md#credentialbitbucketAuthModes)** +**Also see: [credential.bitbucketAuthModes][credential-bitbucketauthmodes]** --- @@ -401,7 +401,7 @@ export GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS=1 Defaults to false/disabled. -**Also see: [credential.bitbucketAlwaysRefreshCredentials](configuration.md#bitbucketAlwaysRefreshCredentials)** +**Also see: [credential.bitbucketAlwaysRefreshCredentials][credential-bitbucketalwaysrefreshcredentials]** --- @@ -433,7 +433,7 @@ SET GCM_GITHUB_AUTHMODES="oauth,basic" export GCM_GITHUB_AUTHMODES="oauth,basic" ``` -**Also see: [credential.gitHubAuthModes](configuration.md#credentialgitHubAuthModes)** +**Also see: [credential.gitHubAuthModes][credential-githubauthmodes]** --- @@ -463,7 +463,7 @@ SET GCM_GITLAB_AUTHMODES="browser" export GCM_GITLAB_AUTHMODES="browser" ``` -**Also see: [credential.gitLabAuthModes](configuration.md#credentialgitLabAuthModes)** +**Also see: [credential.gitLabAuthModes][credential-gitlabauthmodes]** --- @@ -486,7 +486,7 @@ SET GCM_NAMESPACE="my-namespace" export GCM_NAMESPACE="my-namespace" ``` -**Also see: [credential.namespace](configuration.md#credentialnamespace)** +**Also see: [credential.namespace][credential-namespace]** --- @@ -496,18 +496,18 @@ Select the type of credential store to use on supported platforms. Default value on Windows is `wincredman`, on macOS is `keychain`, and is unset on Linux. -**Note:** See more information about configuring secret stores [here](credstores.md). +**Note:** For more information about configuring secret stores see the [credential stores documentation][credential-stores]. Value|Credential Store|Platforms -|-|- _(unset)_|Windows: `wincredman`, macOS: `keychain`, Linux: _(none)_|- `wincredman`|Windows Credential Manager (not available over SSH).|Windows -`dpapi`|DPAPI protected files. Customize the DPAPI store location with [`GCM_DPAPI_STORE_PATH`](#gcm_dpapi_store_path)|Windows +`dpapi`|DPAPI protected files. Customize the DPAPI store location with [`GCM_DPAPI_STORE_PATH`][gcm-dpapi-store-path]|Windows `keychain`|macOS Keychain.|macOS -`secretservice`|[freedesktop.org Secret Service API](https://specifications.freedesktop.org/secret-service/) via [libsecret](https://wiki.gnome.org/Projects/Libsecret) (requires a graphical interface to unlock secret collections).|Linux -`gpg`|Use GPG to store encrypted files that are compatible with the [`pass` utility](https://www.passwordstore.org/) (requires GPG and `pass` to initialize the store).|macOS, Linux -`cache`|Git's built-in [credential cache](https://git-scm.com/docs/git-credential-cache).|Windows, macOS, Linux -`plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`GCM_PLAINTEXT_STORE_PATH`](#gcm_plaintext_store_path).|Windows, macOS, Linux +`secretservice`|[freedesktop.org Secret Service API][freedesktop-ss] via [libsecret][libsecret] (requires a graphical interface to unlock secret collections).|Linux +`gpg`|Use GPG to store encrypted files that are compatible with the [`pass` utility][passwordstore] (requires GPG and `pass` to initialize the store).|macOS, Linux +`cache`|Git's built-in [credential cache][git-credential-cache].|Windows, macOS, Linux +`plaintext`|Store credentials in plaintext files (**UNSECURE**). Customize the plaintext store location with [`GCM_PLAINTEXT_STORE_PATH`][gcm-plaintext-store-path].|Windows, macOS, Linux #### Windows @@ -521,14 +521,14 @@ SET GCM_CREDENTIAL_STORE="gpg" export GCM_CREDENTIAL_STORE="gpg" ``` -**Also see: [credential.credentialStore](configuration.md#credentialcredentialstore)** +**Also see: [credential.credentialStore][credential-credentialstore]** --- ### GCM_CREDENTIAL_CACHE_OPTIONS -Pass [options](https://git-scm.com/docs/git-credential-cache#_options) -to the Git credential cache when [`GCM_CREDENTIAL_STORE`](#GCM_CREDENTIAL_STORE) +Pass [options][git-cache-options] +to the Git credential cache when [`GCM_CREDENTIAL_STORE`][gcm-credential-store] is set to `cache`. This allows you to select a different amount of time to cache credentials (the default is 900 seconds) by passing `"--timeout "`. Use of other options like `--socket` is untested @@ -548,13 +548,13 @@ SET GCM_CREDENTIAL_CACHE_OPTIONS="--timeout 300" export GCM_CREDENTIAL_CACHE_OPTIONS="--timeout 300" ``` -**Also see: [credential.cacheOptions](configuration.md#credentialcacheoptions)** +**Also see: [credential.cacheOptions][credential-cacheoptions]** --- ### GCM_PLAINTEXT_STORE_PATH -Specify a custom directory to store plaintext credential files in when [`GCM_CREDENTIAL_STORE`](#GCM_CREDENTIAL_STORE) is set to `plaintext`. +Specify a custom directory to store plaintext credential files in when [`GCM_CREDENTIAL_STORE`][gcm-credential-store] is set to `plaintext`. Defaults to the value `~/.gcm/store` or `%USERPROFILE%\.gcm\store`. @@ -570,13 +570,13 @@ SETX GCM_PLAINTEXT_STORE_PATH=D:\credentials export GCM_PLAINTEXT_STORE_PATH=/mnt/external-drive/credentials ``` -**Also see: [credential.plaintextStorePath](configuration.md#credentialplaintextstorepath)** +**Also see: [credential.plaintextStorePath][credential-plain-text-store]** --- ### GCM_DPAPI_STORE_PATH -Specify a custom directory to store DPAPI protected credential files in when [`GCM_CREDENTIAL_STORE`](#GCM_CREDENTIAL_STORE) is set to `dpapi`. +Specify a custom directory to store DPAPI protected credential files in when [`GCM_CREDENTIAL_STORE`][gcm-credential-store] is set to `dpapi`. Defaults to the value `%USERPROFILE%\.gcm\dpapi_store`. @@ -586,7 +586,7 @@ Defaults to the value `%USERPROFILE%\.gcm\dpapi_store`. SETX GCM_DPAPI_STORE_PATH=D:\credentials ``` -**Also see: [credential.dpapiStorePath](configuration.md#credentialdpapistorepath)** +**Also see: [credential.dpapiStorePath][credential-dpapi-store-path]** --- @@ -612,7 +612,7 @@ Specify which authentication flow should be used when performing Microsoft authe Defaults to `auto`. -**Note:** If [`GCM_MSAUTH_USEBROKER`](#gcm_msauth_usebroker-experimental) is set to `true` +**Note:** If [`GCM_MSAUTH_USEBROKER`][gcm-msauth-usebroker] is set to `true` and the operating system authentication broker is available, all flows will be delegated to the broker. If both of those things are true, then the value of `GCM_MSAUTH_FLOW` has no effect. @@ -636,7 +636,7 @@ SET GCM_MSAUTH_FLOW="devicecode" export GCM_MSAUTH_FLOW="devicecode" ``` -**Also see: [credential.msauthFlow](configuration.md#credentialmsauthflow)** +**Also see: [credential.msauthFlow][credential-msauth-flow]** --- @@ -646,7 +646,7 @@ Use the operating system account manager where available. Defaults to `false`. This default is subject to change in the future. -_**Note:** before you enable this option on Windows, please [review the details](windows-broker.md) about what this means to your local Windows user account._ +_**Note:** before you enable this option on Windows, please [review the details][windows-broker] about what this means to your local Windows user account._ Value|Description -|- @@ -665,7 +665,7 @@ SET GCM_MSAUTH_USEBROKER="true" export GCM_MSAUTH_USEBROKER="false" ``` -**Also see: [credential.msauthUseBroker](configuration.md#credentialmsauthusebroker-experimental)** +**Also see: [credential.msauthUseBroker][credential-msauth-usebroker]** --- @@ -680,7 +680,7 @@ Value|Description `pat` _(default)_|Azure DevOps personal access tokens `oauth`|Microsoft identity OAuth tokens (AAD or MSA tokens) -More information about Azure Access tokens can be found [here](azrepos-users-and-tokens.md). +More information about Azure Access tokens can be found [here][azure-access-tokens]. #### Windows @@ -694,4 +694,44 @@ SET GCM_AZREPOS_CREDENTIALTYPE="oauth" export GCM_AZREPOS_CREDENTIALTYPE="oauth" ``` -**Also see: [credential.azreposCredentialType](configuration.md#azreposcredentialtype)** +**Also see: [credential.azreposCredentialType][credential-azrepos-credential-type]** + +[autodetect]: autodetect.md +[azure-access-tokens]: azrepos-users-and-tokens.md +[configuration]: configuration.md +[credential-allowwindowsauth]: environment.md#credentialallowWindowsAuth +[credential-authority]: configuration.md#credentialauthority-deprecated +[credential-autodetecttimeout]: configuration.md#credentialautodetecttimeout +[credential-azrepos-credential-type]: configuration.md#azreposcredentialtype +[credential-bitbucketalwaysrefreshcredentials]: configuration.md#bitbucketAlwaysRefreshCredentials +[credential-bitbucketauthmodes]: configuration.md#credentialbitbucketAuthModes +[credential-cacheoptions]: configuration.md#credentialcacheoptions +[credential-credentialstore]: configuration.md#credentialcredentialstore +[credential-dpapi-store-path]: configuration.md#credentialdpapistorepath +[credential-githubauthmodes]: configuration.md#credentialgitHubAuthModes +[credential-gitlabauthmodes]: configuration.md#credentialgitLabAuthModes +[credential-guiprompt]: configuration.md#credentialguiprompt +[credential-httpproxy]: configuration.md#credentialhttpProxy-deprecated +[credential-interactive]: configuration.md#credentialinteractive +[credential-namespace]: configuration.md#credentialnamespace +[credential-msauth-flow]: configuration.md#credentialmsauthflow +[credential-msauth-usebroker]: configuration.md#credentialmsauthusebroker-experimental +[credential-plain-text-store]: configuration.md#credentialplaintextstorepath +[credential-provider]: configuration.md#credentialprovider +[credential-stores]: credstores.md +[default-values]: enterprise-config.md +[freedesktop-ss]: https://specifications.freedesktop.org/secret-service/ +[gcm]: usage.md +[gcm-interactive]: #gcm_interactive +[gcm-credential-store]: #GCM_CREDENTIAL_STORE +[gcm-dpapi-store-path]: #gcm_dpapi_store_path +[gcm-plaintext-store-path]: #gcm_plaintext_store_path +[gcm-msauth-usebroker]: #gcm_msauth_usebroker-experimental +[git-cache-options]: https://git-scm.com/docs/git-credential-cache#_options +[git-credential-cache]: https://git-scm.com/docs/git-credential-cache +[git-httpproxy]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy +[network-http-proxy]: netconfig.md#http-proxy +[libsecret]: https://wiki.gnome.org/Projects/Libsecret +[migration-guide]: migration.md#gcm_authority +[passwordstore]: https://www.passwordstore.org/ +[windows-broker]: windows-broker.md diff --git a/docs/faq.md b/docs/faq.md index b61d43d0e..a6067dfb3 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -10,9 +10,9 @@ Please follow these steps to diagnose or resolve the problem: 1. If you are experiencing a Git authentication problem using an editor, IDE or other tool, try performing the same operation from the terminal. Does this still fail? If the operation succeeds from the terminal please include details of the specific tool and version in any issue reports. -1. Set the environment variable `GCM_TRACE` and run the Git operation again. Find instructions [here](environment.md#GCM_TRACE). +1. Set the environment variable `GCM_TRACE` and run the Git operation again. Find instructions in the [environment doc][env-trace]. -1. If all else fails, create an issue [here](https://github.com/GitCredentialManager/git-credential-manager/issues/create), making sure to include the trace log. +1. If all else fails, create an issue [here][create-issue], making sure to include the trace log. ### Q: I got an error saying unsecure HTTP is not supported @@ -22,15 +22,15 @@ Please make sure your remote URLs use "https://" rather than "http://". ### Q: I got an authentication error and I am behind a network proxy -You probably need to configure Git and GCM to use a proxy. Please see detailed information [here](https://aka.ms/gcm/httpproxy). +You probably need to configure Git and GCM to use a proxy. Please see detailed information in the [network config doc][netconfig-http-proxy]. ### Q: I'm getting errors about picking a credential store on Linux -On Linux you must [select and configure a credential store](https://aka.ms/gcm/credstores), as due to the varied nature of distributions and installations, we cannot guarantee a suitable storage solution is available. +On Linux you must [select and configure a credential store][credstores], as due to the varied nature of distributions and installations, we cannot guarantee a suitable storage solution is available. ## About the project -### Q: How does this project relate to [Git Credential Manager for Windows](https://github.com/Microsoft/Git-Credential-Manager-for-Windows) and [Git Credential Manager for Mac and Linux](https://github.com/Microsoft/Git-Credential-Manager-for-Mac-and-Linux)? +### Q: How does this project relate to [Git Credential Manager for Windows][gcm-windows] and [Git Credential Manager for Mac and Linux][gcm-linux]? Git Credential Manager for Windows (GCM Windows) is a .NET Framework-based Git credential helper which runs on Windows. Likewise the Git Credential Manager for Mac and Linux (Java GCM) is a Java-based Git credential helper that runs only on macOS and Linux. Although both of these projects aim to solve the same problem (providing seamless multi-factor HTTPS authentication with Git), they are based on different codebases and languages which is becoming hard to manage to ensure feature parity. @@ -43,7 +43,7 @@ Yes. Git Credential Manager for Windows (GCM Windows) is no longer receiving upd ### Q: Does this mean the Java-based GCM for Mac/Linux is deprecated? -Yes. Usage of Git Credential Manager for Mac and Linux (Java GCM) should be replaced with GCM or SSH keys. If you wish to install GCM on macOS or Linux, please follow the [download and installation instructions](../README.md#download-and-install). +Yes. Usage of Git Credential Manager for Mac and Linux (Java GCM) should be replaced with GCM or SSH keys. If you wish to install GCM on macOS or Linux, please follow the [download and installation instructions][download-and-install]. ### Q: I want to use SSH @@ -51,9 +51,9 @@ GCM is only useful for HTTP(S)-based remotes. Git supports SSH out-of-the box so To use SSH please follow the below links: -- [Azure DevOps](https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops) -- [GitHub](https://help.github.com/en/articles/connecting-to-github-with-ssh) -- [Bitbucket](https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html) +- [Azure DevOps][azure-ssh] +- [GitHub][github-ssh] +- [Bitbucket][bitbucket-ssh] ### Q: Are HTTP(S) remotes preferred over SSH? @@ -81,11 +81,11 @@ We are happy to accept proposals and/or contributions to enable GCM to run on ot Due to the design of Git and credential helpers such as GCM, we need this setting to make Git use the full remote URL (including the path component) when communicating with GCM. The new `dev.azure.com` format of Azure DevOps URLs means the account name is now part of the path component (for example: `https://dev.azure.com/contoso/...`). The Azure DevOps account name is required in order to resolve the correct authority for authentication (which Azure AD tenant backs this account, or if it is backed by Microsoft personal accounts). -In the older GCM for Windows product, the solution to the same problem was a "hack". GCM for Windows would walk the process tree looking for the `git-remote-https.exe` process, and attempt to read/parse the process environment block looking for the command line arguments (that contained the full remote URL). This is fragile and not a cross-platform solution, hense the need for the `credential.useHttpPath` setting with GCM. +In the older GCM for Windows product, the solution to the same problem was a "hack". GCM for Windows would walk the process tree looking for the `git-remote-https.exe` process, and attempt to read/parse the process environment block looking for the command line arguments (that contained the full remote URL). This is fragile and not a cross-platform solution, hence the need for the `credential.useHttpPath` setting with GCM. ### Why does GCM take so long at startup the first time? -GCM will [autodetect](autodetect.md) what kind of Git host it's talking to. GitHub, Bitbucket, and Azure DevOps each have their own form(s) of authentication, plus there's a "generic" username and password option. +GCM will [autodetect][autodetect] what kind of Git host it's talking to. GitHub, Bitbucket, and Azure DevOps each have their own form(s) of authentication, plus there's a "generic" username and password option. For the hosted versions of these services, GCM can guess from the URL which service to use. But for on-premises versions which would have unique URLs, GCM will probe with a network call. GCM caches the results of the probe, so it should be faster on the second and later invocations. @@ -100,24 +100,24 @@ Generic|`git config --global credential.https://example.com.provider generic` ### How do I fix "Could not create SSL/TLS secure channel" errors on Windows 7? -This likely indicates that you don't have newer TLS versions available. Please [follow Microsoft's guide](https://support.microsoft.com/topic/update-to-enable-tls-1-1-and-tls-1-2-as-default-secure-protocols-in-winhttp-in-windows-c4bd73d2-31d7-761e-0178-11268bb10392) for enabling TLS 1.1 and 1.2 on your machine, specifically the **SChannel** instructions. You'll need to be on at least Windows 7 SP1, and in the end you should have a `TLS 1.2` key with `DisabledByDefault` set to `0`. You can also read [more from Microsoft](https://docs.microsoft.com/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/dn786418(v=ws.11)#tls-12) on this change. +This likely indicates that you don't have newer TLS versions available. Please [follow Microsoft's guide][enable-windows-ssh] for enabling TLS 1.1 and 1.2 on your machine, specifically the **SChannel** instructions. You'll need to be on at least Windows 7 SP1, and in the end you should have a `TLS 1.2` key with `DisabledByDefault` set to `0`. You can also read [more from Microsoft][windows-server-tls] on this change. ### How do I use GCM with Windows Subsystem for Linux (WSL)? -Follow the instructions in [our WSL guide](wsl.md) carefully. Especially note the need to run `git config --global credential.https://dev.azure.com.useHttpPath true` _within_ WSL if you're using Azure DevOps. +Follow the instructions in [our WSL guide][wsl] carefully. Especially note the need to run `git config --global credential.https://dev.azure.com.useHttpPath true` _within_ WSL if you're using Azure DevOps. ### Does GCM work with multiple users? If so, how? -That's a fairly complicated question to answer, but in short, yes. See [our document on multiple users](multiple-users.md) for details. +That's a fairly complicated question to answer, but in short, yes. See [our document on multiple users][multiple-users] for details. ### How can I disable GUI dialogs and prompts? There are various environment variables and configuration options available to customize how GCM will prompt you (or not) for input. Please see the following: -- [`GCM_INTERACTIVE`](environment.md#GCM_INTERACTIVE) / [`credential.interactive`](configuration.md#credentialinteractive) -- [`GCM_GUI_PROMPT`](environment.md#GCM_GUI_PROMPT) / [`credential.guiPrompt`](configuration.md#credentialguiprompt) -- [`GIT_TERMINAL_PROMPT`](https://git-scm.com/docs/git#Documentation/git.txt-codeGITTERMINALPROMPTcode) (note this is a _Git setting_ that will affect Git as well as GCM) +- [`GCM_INTERACTIVE`][env-interactive] / [`credential.interactive`][config-interactive] +- [`GCM_GUI_PROMPT`][env-gui-prompt] / [`credential.guiPrompt`][config-gui-prompt] +- [`GIT_TERMINAL_PROMPT`][git-term-prompt] (note this is a _Git setting_ that will affect Git as well as GCM) ### How can I extend GUI prompts/integrate prompts with my application? @@ -140,27 +140,54 @@ text-based prompts instead. ### How do I revoke consent for GCM for GitHub.com? In your GitHub user settings, navigate to -[Integrations > Applications > Authorized OAuth Apps > Git Credential Manager](https://github.com/settings/connections/applications/0120e057bd645470c1ed) +[Integrations > Applications > Authorized OAuth Apps > Git Credential Manager][github-connected-apps] and pick "Revoke access". -![Revoke GCM OAuth app access](img/github-oauthapp-revoke.png) +![Revoke GCM OAuth app access][github-oauthapp-revoke] After revoking access, any tokens created by GCM will be invalidated and can no longer be used to access your repositories. The next time GCM attempts to access GitHub.com you will be prompted to consent again. ### I used the install from source script to install GCM on my Linux distribution. Now how can I uninstall GCM and its dependencies? -Please see full instructions [here](./linux-fromsrc-uninstall.md). +Please see full instructions [here][linux-uninstall-from-src]. ### How do I revoke access for a GitLab OAuth application? There are some scenarios (e.g. updated scopes) for which you will need to manually revoke and re-authorize access for a GitLab OAuth application. You can do so by: -1. Navigating to [the **Applications** page within your **User Settings**](https://gitlab.com/-/profile/applications). +1. Navigating to [the **Applications** page within your **User Settings**][gitlab-apps]. 2. Scrolling to **Authorized applications**. 3. Clicking the **Revoke** button next to the name of the application for which you would like to revoke access (Git Credential Manager is used here for demonstration purposes). - ![Button to revoke GitLab OAuth Application access](./img/gitlab-oauthapp-revoke.png) + ![Button to revoke GitLab OAuth Application access][gitlab-oauthapp-revoke] 4. Waiting for a notification stating **The application was revoked access**. - ![Notifaction of successful revocation](./img/gitlab-oauthapp-revoked.png) + ![Notifaction of successful revocation][gitlab-oauthapp-revoked] 5. Re-authorizing the application with the new scope (GCM should automatically initiate this flow for you next time access is requested). + +[autodetect]: autodetect.md +[azure-ssh]: https://docs.microsoft.com/en-us/azure/devops/repos/git/use-ssh-keys-to-authenticate?view=azure-devops +[bitbucket-ssh]: https://confluence.atlassian.com/bitbucket/ssh-keys-935365775.html +[config-gui-prompt]: configuration.md#credentialguiprompt +[config-interactive]: configuration.md#credentialinteractive +[create-issue]: https://github.com/GitCredentialManager/git-credential-manager/issues/create +[credstores]: credstores.md +[download-and-install]: ../README.md#download-and-install +[enable-windows-ssh]: https://support.microsoft.com/topic/update-to-enable-tls-1-1-and-tls-1-2-as-default-secure-protocols-in-winhttp-in-windows-c4bd73d2-31d7-761e-0178-11268bb10392 +[env-gui-prompt]: environment.md#GCM_GUI_PROMPT +[env-interactive]: environment.md#GCM_INTERACTIVE +[env-trace]: environment.md#GCM_TRACE +[gcm-linux]: https://github.com/Microsoft/Git-Credential-Manager-for-Mac-and-Linux +[gcm-windows]: https://github.com/Microsoft/Git-Credential-Manager-for-Windows +[git-term-prompt]: https://git-scm.com/docs/git#Documentation/git.txt-codeGITTERMINALPROMPTcode +[github-connected-apps]: https://github.com/settings/connections/applications/0120e057bd645470c1ed +[github-oauthapp-revoke]: img/github-oauthapp-revoke.png +[github-ssh]: https://help.github.com/en/articles/connecting-to-github-with-ssh +[gitlab-apps]: https://gitlab.com/-/profile/applications +[gitlab-oauthapp-revoke]: ./img/gitlab-oauthapp-revoke.png +[gitlab-oauthapp-revoked]: ./img/gitlab-oauthapp-revoked.png +[multiple-users]: multiple-users.md +[netconfig-http-proxy]: netconfig.md#http-proxy +[linux-uninstall-from-src]: ./linux-fromsrc-uninstall.md +[windows-server-tls]: https://docs.microsoft.com/previous-versions/windows/it-pro/windows-server-2012-R2-and-2012/dn786418(v=ws.11)#tls-12 +[wsl]: wsl.md diff --git a/docs/github-apideprecation.md b/docs/github-apideprecation.md index 9d5c3b9a3..e355c70d5 100644 --- a/docs/github-apideprecation.md +++ b/docs/github-apideprecation.md @@ -2,14 +2,13 @@ ## What's going on? -GitHub now [requires token-based authentication](https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/) to +GitHub now [requires token-based authentication][token-auth] to call their APIs, and in the future, use Git itself. This means Git credential helpers such as [Git Credential Manager (GCM) for -Windows](https://github.com/microsoft/Git-Credential-Manager-for-Windows), and -old versions of [GCM](https://aka.ms/gcm) that offer username/password -flows **will not be able to create new access tokens** for accessing Git -repositories. +Windows][gcm-windows], and old versions of [GCM][gcm] that offer +username/password flows **will not be able to create new access tokens** for +accessing Git repositories. If you already have tokens generated by Git credential helpers like GCM for Windows, they will continue to work until they expire or are revoked/deleted. @@ -22,15 +21,15 @@ The best thing to do right now is upgrade to the latest Git for Windows (at least version 2.29), which includes a version of Git Credential Manager that uses supported OAuth token-based authentication. -[Download the latest Git for Windows ⬇️](https://git-scm.com/download/win) +[Download the latest Git for Windows ⬇️][git-windows] ### Visual Studio users Please update to the latest supported release of Visual Studio, that includes GCM and support for OAuth token-based authentication. -- [Visual Studio 2019 ⬇️](https://docs.microsoft.com/en-us/visualstudio/install/update-visual-studio?view=vs-2019) -- [Visual Studio 2017 ⬇️](https://docs.microsoft.com/en-us/visualstudio/install/update-visual-studio?view=vs-2017) +- [Visual Studio 2019 ⬇️][vs-2019] +- [Visual Studio 2017 ⬇️][vs-2017] ### SSH, macOS, and Linux users @@ -38,7 +37,7 @@ If you are using SSH this change does **not** affect you. If you are using an older version of Git Credential Manager (before 2.0.124-beta) please upgrade to the latest version following [these -instructions](https://github.com/GitCredentialManager/git-credential-manager#download-and-install). +instructions][gcm-install]. ## What if I cannot upgrade Git for Windows? @@ -46,18 +45,18 @@ If you are unable to upgrade Git for Windows, you can manually install Git Credential Manager as a standalone install. This will override the older, GCM for Windows bundled with the Git for Windows installation. -[Download Git Credential Manager standalone ⬇️](https://aka.ms/gcm/latest) +[Download Git Credential Manager standalone ⬇️][gcm-latest] ## What if I cannot use Git Credential Manager? If you are unable to use Git Credential Manager due to a bug or -compatibility issue we'd [like to know why](https://github.com/GitCredentialManager/git-credential-manager/issues/new/choose)! +compatibility issue we'd [like to know why][gcm-new-issue]! ## Help! I cannot make any changes to my Windows machine without an Administrator If you do not have permission to change your installation (for example in a corporate environment) you can use the per-user installer. Check out the [latest -release](https://aka.ms/gcm/latest) and download the `gcmcoreuser-win-*.exe` +release][gcm-latest] and download the `gcmcoreuser-win-*.exe` executable. ### Help! I still cannot or don't want to install anything @@ -67,26 +66,27 @@ There is a workaround which should work and doesn't require installing anything. 1. Tell your system administrator they should start planning to upgrade the installed version of Git for Windows to at least 2.29! 😁 -1. [Create a new personal access token](https://github.com/settings/tokens/new?scopes=repo,gist,workflow) (see official [documentation](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)) +1. [Create a new personal access token][github-pat] (see official + [documentation][github-pat-docs]) 1. Enter a name ("note") for the token and ensure the `repo`, `gist`, and `workflow` scopes are selected: - ![image](https://user-images.githubusercontent.com/5658207/95448332-1beb2000-095b-11eb-9a48-9c05b1926a6b.png) + ![image][github-pat-name-image] ... - ![image](https://user-images.githubusercontent.com/5658207/95447304-6f5c6e80-0959-11eb-924b-50b86c2b3d77.png) + ![image][github-pat-repo-scope-image] ... - ![image](https://user-images.githubusercontent.com/5658207/95447450-a3d02a80-0959-11eb-82a8-2d2834d5aa16.png) + ![image][github-pat-gist-scope-image] ... - ![image](https://user-images.githubusercontent.com/5658207/95447343-7b483080-0959-11eb-8e00-151d53893f3f.png) + ![image][github-pat-workflow-scope-image] 1. Click "Generate Token" - ![image](https://user-images.githubusercontent.com/5658207/95448393-31f8e080-095b-11eb-9568-cfd1c567a65c.png) + ![image][github-generate-pat-image] 1. **[IMPORTANT]** Keep the resulting page open as this contains your new token (this will only be displayed once!) - ![image](https://user-images.githubusercontent.com/5658207/95448288-ff4ee800-095a-11eb-9709-8e37bde8b716.png) + ![image][github-display-pat-image] 1. Save the generated PAT in the Windows Credential Manager: @@ -100,13 +100,13 @@ There is a workaround which should work and doesn't require installing anything. You will be prompted to enter a password – copy the newly generated PAT in step 4 and paste it here, and press the `Enter` key - ![image](https://user-images.githubusercontent.com/5658207/95448479-4fc64580-095b-11eb-9970-0b6faf7f4ae7.png) + ![image][windows-save-pat-cli-image] 1. If you do not wish to use the command-line, [open the Credential Manager - via Control Panel](https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0) + via Control Panel][windows-credential-manager] and select the "Windows Credentials" tab. - ![image](https://user-images.githubusercontent.com/5658207/96468389-f6e09200-1223-11eb-9993-ae7b4096b769.png) + ![image][windows-gui-credentials-image] Click "Add a generic credential", and enter the following details: @@ -114,12 +114,35 @@ There is a workaround which should work and doesn't require installing anything. - Username: `PersonalAccessToken` - Password: _(copy and paste the PAT generated in step 4 here)_ - ![image](https://user-images.githubusercontent.com/5658207/96468318-ddd7e100-1223-11eb-8cd4-aa118493c538.png) + ![image][windows-gui-add-pat-image] ## What about GitHub Enterprise Server (GHES)? -As mentioned in [the blog post](https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/), +As mentioned in [the blog post][github-token-authentication-requirements], the new token-based authentication requirements **DO NOT** apply to GHES: > We have not announced any changes to GitHub Enterprise Server, which remains > unaffected at this time. + +[token-auth]: https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/ +[gcm]: https://aka.ms/gcm +[gcm-install]: ../README.md#download-and-install +[gcm-latest]: https://aka.ms/gcm/latest +[gcm-new-issue]: https://github.com/GitCredentialManager/git-credential-manager/issues/new/choose +[gcm-windows]: https://github.com/microsoft/Git-Credential-Manager-for-Windows +[git-windows]: https://git-scm.com/download/win +[github-display-pat-image]: https://user-images.githubusercontent.com/5658207/95448288-ff4ee800-095a-11eb-9709-8e37bde8b716.png +[github-generate-pat-image]: https://user-images.githubusercontent.com/5658207/95448393-31f8e080-095b-11eb-9568-cfd1c567a65c.png +[github-pat]: https://github.com/settings/tokens/new?scopes=repo,gist,workflow +[github-pat-docs]: https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token +[github-pat-gist-scope-image]: https://user-images.githubusercontent.com/5658207/95447450-a3d02a80-0959-11eb-82a8-2d2834d5aa16.png +[github-pat-name-image]: https://user-images.githubusercontent.com/5658207/95448332-1beb2000-095b-11eb-9a48-9c05b1926a6b.png +[github-pat-repo-scope-image]: https://user-images.githubusercontent.com/5658207/95447304-6f5c6e80-0959-11eb-924b-50b86c2b3d77.png +[github-pat-workflow-scope-image]: https://user-images.githubusercontent.com/5658207/95447343-7b483080-0959-11eb-8e00-151d53893f3f.png +[github-token-authentication-requirements]: https://github.blog/2020-07-30-token-authentication-requirements-for-api-and-git-operations/ +[windows-save-pat-cli-image]: https://user-images.githubusercontent.com/5658207/95448479-4fc64580-095b-11eb-9970-0b6faf7f4ae7.png +[vs-2019]: https://docs.microsoft.com/en-us/visualstudio/install/update-visual-studio?view=vs-2019 +[vs-2017]: https://docs.microsoft.com/en-us/visualstudio/install/update-visual-studio?view=vs-2017 +[windows-credential-manager]: https://support.microsoft.com/en-us/windows/accessing-credential-manager-1b5c916a-6a16-889f-8581-fc16e8165ac0 +[windows-gui-add-pat-image]: https://user-images.githubusercontent.com/5658207/96468318-ddd7e100-1223-11eb-8cd4-aa118493c538.png +[windows-gui-credentials-image]: https://user-images.githubusercontent.com/5658207/96468389-f6e09200-1223-11eb-9993-ae7b4096b769.png diff --git a/docs/gitlab.md b/docs/gitlab.md index 1720b52c9..1b9687a6b 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -1,12 +1,12 @@ # GitLab support -Git Credential Manager supports [gitlab.com](https://gitlab.com) out the box. +Git Credential Manager supports [gitlab.com][gitlab] out the box. ## Using on a another instance To use on another instance, eg. `https://gitlab.example.com` requires setup and configuration: -1. [Create an OAuth application](https://docs.gitlab.com/ee/integration/oauth_provider.html). This can be at the user, group or instance level. Specify a name and use a redirect URI of `http://127.0.0.1/`. _Unselect_ the 'Confidential' option. Set the 'write_repository' and 'read_repository' scopes. +1. [Create an OAuth application][gitlab-oauth]. This can be at the user, group or instance level. Specify a name and use a redirect URI of `http://127.0.0.1/`. _Unselect_ the 'Confidential' option. Set the 'write_repository' and 'read_repository' scopes. 1. Copy the application ID and configure `git config --global credential.https://gitlab.example.com.GitLabDevClientId ` 1. Copy the application secret and configure `git config --global credential.https://gitlab.example.com.GitLabDevClientSecret ` 1. Configure authentication modes to include 'browser' `git config --global credential.https://gitlab.example.com.gitLabAuthModes browser` @@ -31,7 +31,7 @@ Select an authentication method for 'https://gitlab.com/': option (enter for default): ``` -If you have a preferred authentication mode, you can specify [credential.gitLabAuthModes](configuration.md#credential.gitLabAuthModes): +If you have a preferred authentication mode, you can specify [credential.gitLabAuthModes][config-gitlab-auth-modes]: ```console git config --global credential.gitlabauthmodes browser @@ -41,6 +41,13 @@ git config --global credential.gitlabauthmodes browser Improved support requires changes in GitLab. Please vote for these issues if they affect you: -1. No support for OAuth device authorization (necessary for machines without web browser): [GitLab issue 332682](https://gitlab.com/gitlab-org/gitlab/-/issues/332682) -1. Only domains with prefix `gitlab.` are recognised as GitLab remotes: [GitLab issue 349464](https://gitlab.com/gitlab-org/gitlab/-/issues/349464) -1. Username/password authentication is suggested even if disabled on server: [GitLab issue 349463](https://gitlab.com/gitlab-org/gitlab/-/issues/349463) +1. No support for OAuth device authorization (necessary for machines without web browser): [GitLab issue 332682][gitlab-issue-332682] +1. Only domains with prefix `gitlab.` are recognised as GitLab remotes: [GitLab issue 349464][gitlab-issue-349464] +1. Username/password authentication is suggested even if disabled on server: [GitLab issue 349463][gitlab-issue-349463] + +[config-gitlab-auth-modes]: configuration.md#credential.gitLabAuthModes +[gitlab]: https://gitlab.com +[gitlab-issue-332682]: https://gitlab.com/gitlab-org/gitlab/-/issues/332682 +[gitlab-issue-349464]: https://gitlab.com/gitlab-org/gitlab/-/issues/349464 +[gitlab-issue-349463]: https://gitlab.com/gitlab-org/gitlab/-/issues/349463 +[gitlab-oauth]: https://docs.gitlab.com/ee/integration/oauth_provider.html diff --git a/docs/hostprovider.md b/docs/hostprovider.md index bfd036363..930717dfb 100644 --- a/docs/hostprovider.md +++ b/docs/hostprovider.md @@ -1,18 +1,5 @@ # Git Credential Manager Host Provider -Property|Value --|- -Author(s)|Matthew John Cheetham ([@mjcheetham](https://github.com/mjcheetham)) -Revision|1.2 -Last updated|2021-01-08 - -## Revision Summary - -- 1.0. Initial revision. -- 1.1. Replaced `GetCredentialKey` with `GetServiceName`. -- 1.2. Added new `IsSupported(HttpResponseMessage)` overload, the optional - `ICommandProvider` interface, and registration priorities. - ## Abstract Git Credential Manger, the cross-platform and cross-host Git credential @@ -20,37 +7,13 @@ helper, can be extended to support any Git hosting service allowing seamless authentication to secured Git repositories by implementing and registering a "host provider". -## Table of Contents - -- [1. Introduction](#1-introduction) - - [1.1. Notational Conventions](#11-notational-conventions) - - [1.2. Abbreviations](#12-abbreviations) -- [2. Implementation](#2-implementation) - - [2.1. Registration](#21-registration) - - [2.1.2. Ordering](#212-ordering) - - [2.2. Handling Requests](#22-handling-requests) - - [2.2.1. Rejecting Requests](#221-rejecting-requests) - - [2.3. Retrieving Credentials](#23-retrieving-credentials) - - [2.3.1 Authentication Prompts](#231-authentication-prompts) - - [2.4. Storing Credentials](#24-storing-credentials) - - [2.5. Erasing Credentials](#25-erasing-credentials) - - [2.6 `HostProvider` base class](#26-hostprovider-base-class) - - [2.6.1 `GetServiceName`](#261-getservicename) - - [2.6.2 `GenerateCredentialAsync`](#262-generatecredentialasync) - - [2.7. External Metadata](#27-external-metadata) -- [3. Helpers](#3-helpers) - - [3.1. Discovery](#31-discovery) -- [4. Error Handling](#4-error-handling) -- [5. Custom Commands](#5-custom-commands) -- [References](#references) - ## 1. Introduction Git Credential Manager (GCM) is a host and platform agnostic Git credential helper application. Support for authenticating to any Git hosting service can be added to GCM by creating a custom "host provider" and registering it within the product. Host providers can be submitted via a pull -request on GitHub at . +request on [the Git Credential Manager repository on GitHub][gcm]. This document outlines the required and expected behaviour of a host provider, and what is required to implement and register one. @@ -60,7 +23,7 @@ and what is required to implement and register one. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in -[[RFC2119](https://tools.ietf.org/html/rfc2119)]. +[[RFC2119][rfc-2119]]. ### 1.2. Abbreviations @@ -72,7 +35,7 @@ Manager for Windows" is abbreviated to "GCM for Windows" or "GCM Windows". "Git Credential Manager for Mac & Linux" is abbreviated to "GCM for Mac/Linux" or "GCM Mac/Linux". -OAuth2 [[RFC6749](https://tools.ietf.org/html/rfc6749)] "access tokens" are +OAuth2 [[RFC6749][rfc-6749]] "access tokens" are abbreviated to "ATs" and "refresh tokens" to "RTs". "Personal Access Tokens" are abbreviated to "PATs". @@ -85,7 +48,7 @@ provider with the application via the host provider registry. Host providers MUST implement the `IHostProvider` interface. They can choose to directly implement the interface they MAY derive from the `HostProvider` abstract class (which itself implements the `IHostProvider` interface) - see -[§2.6](#26-hostprovider-base-class). +[2.6][hostprovider-base-class]. Implementors MUST implement all interface properties and abstract methods. @@ -371,11 +334,18 @@ If a host provider wishes to surface custom commands the SHOULD implement the Each provider is given the opportunity to create a single `ProviderCommand` instance to which further sub-commands can be parented to. Commanding is -provided by the `System.CommandLine` API library [[1](#references)]. +provided by the `System.CommandLine` API library [[1][references]]. There are no limitations on what format sub-commands, arguments, or options must take, but implementors SHOULD attempt to follow existing practices and styles. ## References -1. `System.CommandLine` API () +1. [`System.CommandLine` API][github-dotnet-cli] + +[gcm]: https://github.com/GitCredentialManager/git-credential-manager +[github-dotnet-cli]: https://github.com/dotnet/command-line-api +[hostprovider-base-class]: #26-hostprovider-base-class +[references]: #references +[rfc-2119]: https://tools.ietf.org/html/rfc2119 +[rfc-6749]: https://tools.ietf.org/html/rfc6749 diff --git a/docs/linux-fromsrc-uninstall.md b/docs/linux-fromsrc-uninstall.md index 878528804..425312dea 100644 --- a/docs/linux-fromsrc-uninstall.md +++ b/docs/linux-fromsrc-uninstall.md @@ -1,6 +1,6 @@ # Uninstalling after installing from source -These instructions will guide you in removing GCM after running the [install from source script](../src/linux/Packaging.Linux/install-from-source.sh) on your Linux distribution. +These instructions will guide you in removing GCM after running the [install from source script][install-from-source] on your Linux distribution. :rotating_light: PROCEED WITH CAUTION :rotating_light: @@ -22,7 +22,7 @@ sudo rm ~/install-from-source.sh ## Debian/Ubuntu -**Note:** If you had a pre-existing installation of dotnet that was not installed via `apt` or `apt-get` when you ran the install from source script, you will need to remove it using [these instructions](https://docs.microsoft.com/en-us/dotnet/core/install/remove-runtime-sdk-versions?pivots=os-linux#uninstall-net) and remove `dotnet-*` from the below command. +**Note:** If you had a pre-existing installation of dotnet that was not installed via `apt` or `apt-get` when you ran the install from source script, you will need to remove it using [these instructions][uninstall-dotnet] and remove `dotnet-*` from the below command. ```console sudo apt remove dotnet-* dpkg-dev apt-transport-https git curl wget @@ -30,7 +30,7 @@ sudo apt remove dotnet-* dpkg-dev apt-transport-https git curl wget ## Linux Mint -**Note:** If you had a pre-existing installation of dotnet when you ran the install from source script that was not located at `~/.dotnet`, you will need to modify the first command below to point to the custom install location. If you would like to remove the specific version of dotnet that the script installed and keep other versions, you can do so with [these instructions](https://docs.microsoft.com/en-us/dotnet/core/install/remove-runtime-sdk-versions?pivots=os-linux#uninstall-net). +**Note:** If you had a pre-existing installation of dotnet when you ran the install from source script that was not located at `~/.dotnet`, you will need to modify the first command below to point to the custom install location. If you would like to remove the specific version of dotnet that the script installed and keep other versions, you can do so with [these instructions][uninstall-dotnet]. ```console sudo rm -rf ~/.dotnet && @@ -39,7 +39,7 @@ sudo apt remove git curl ## Fedora/CentOS/RHEL -**Note:** If you had a pre-existing installation of dotnet when you ran the install from source script that was not located at `~/.dotnet`, you will need to modify the first command below to point to the custom install location. If you would like to remove the specific version of dotnet that the script installed and keep other versions, you can do so with [these instructions](https://docs.microsoft.com/en-us/dotnet/core/install/remove-runtime-sdk-versions?pivots=os-linux#uninstall-net). +**Note:** If you had a pre-existing installation of dotnet when you ran the install from source script that was not located at `~/.dotnet`, you will need to modify the first command below to point to the custom install location. If you would like to remove the specific version of dotnet that the script installed and keep other versions, you can do so with [these instructions][uninstall-dotnet]. ```console sudo rm -rf ~/.dotnet @@ -47,9 +47,12 @@ sudo rm -rf ~/.dotnet ## Alpine -**Note:** If you had a pre-existing installation of dotnet when you ran the install from source script that was not located at `~/.dotnet`, you will need to modify the first command below to point to the custom install location. If you would like to remove the specific version of dotnet that the script installed and keep other versions, you can do so with [these instructions](https://docs.microsoft.com/en-us/dotnet/core/install/remove-runtime-sdk-versions?pivots=os-linux#uninstall-net). +**Note:** If you had a pre-existing installation of dotnet when you ran the install from source script that was not located at `~/.dotnet`, you will need to modify the first command below to point to the custom install location. If you would like to remove the specific version of dotnet that the script installed and keep other versions, you can do so with [these instructions][uninstall-dotnet]. ```console sudo rm -rf ~/.dotnet && sudo apk del icu-libs krb5-libs libgcc libintl libssl1.1 libstdc++ zlib which bash coreutils gcompat git curl ``` + +[install-from-source]: ../src/linux/Packaging.Linux/install-from-source.sh +[uninstall-dotnet]: https://docs.microsoft.com/en-us/dotnet/core/install/remove-runtime-sdk-versions?pivots=os-linux#uninstall-net diff --git a/docs/multiple-users.md b/docs/multiple-users.md index 7446aef0e..8fb3e0c71 100644 --- a/docs/multiple-users.md +++ b/docs/multiple-users.md @@ -50,4 +50,6 @@ git remote set-url origin https://employee9999@example.com/big-company/secret-re ## Azure DevOps -[Azure DevOps has some additional, optional complexity](azrepos-users-and-tokens.md) which you should also be aware of if you're using it. +[Azure DevOps has some additional, optional complexity][azure-access-tokens] which you should also be aware of if you're using it. + +[azure-access-tokens]: azrepos-users-and-tokens.md diff --git a/docs/netconfig.md b/docs/netconfig.md index 88aab2b7f..8d9c4bfa8 100644 --- a/docs/netconfig.md +++ b/docs/netconfig.md @@ -1,12 +1,12 @@ # Network and HTTP configuration -Git Credential Manager's network and HTTP(S) behavior can be configured in a few different ways via [environment variables](environment.md) and [configuration options](configuration.md). +Git Credential Manager's network and HTTP(S) behavior can be configured in a few different ways via [environment variables][environment] and [configuration options][configuration]. ## HTTP Proxy If your computer sits behind a network firewall that requires the use of a proxy server to reach repository remotes or the wider Internet, there are various methods for configuring GCM to use a proxy. -The simplest way to configure a proxy for _all_ HTTP(S) remotes is to [use the standard Git HTTP(S) proxy setting `http.proxy`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy). +The simplest way to configure a proxy for _all_ HTTP(S) remotes is to [use the standard Git HTTP(S) proxy setting `http.proxy`][git-http-proxy]. For example to configure a proxy for all remotes for the current user: @@ -14,7 +14,7 @@ For example to configure a proxy for all remotes for the current user: git config --global http.proxy http://proxy.example.com ``` -To specify a proxy for a particular remote you can [use the `remote..proxy` repository-level setting](https://git-scm.com/docs/git-config#Documentation/git-config.txt-remoteltnamegtproxy), for example: +To specify a proxy for a particular remote you can [use the `remote..proxy` repository-level setting][git-remote-name-proxy], for example: ```shell git config --local remote.origin.proxy http://proxy.example.com @@ -26,7 +26,7 @@ The advantage to using these standard configuration options is that in addition Some proxy servers do not accept anonymous connections and require authentication. In order to specify the credentials to be used with a proxy, you can specify the username and password as part of the proxy URL setting. -The format follows [RFC 3986 section 3.2.1](https://tools.ietf.org/html/rfc3986#section-3.2.1) by including the credentials in the 'user information' part of the URI. The password is optional. +The format follows [RFC 3986 section 3.2.1][rfc-3986-321] by including the credentials in the 'user information' part of the URI. The password is optional. ```text protocol://username[:password]@hostname @@ -38,7 +38,7 @@ For example, to specify the username `john.doe` and the password `letmein123` fo https://john.doe:letmein123@proxy.example.com ``` -If you have special characters (as defined by [RFC 3986 section 2.2](https://tools.ietf.org/html/rfc3986#section-2.2)) in your username or password such as `:`, `@`, or any other non-URL friendly character you can URL-encode them ([section 2.1](https://tools.ietf.org/html/rfc3986#section-2.2)). +If you have special characters (as defined by [RFC 3986 section 2.2][rfc-3986-22]) in your username or password such as `:`, `@`, or any other non-URL friendly character you can URL-encode them ([section 2.1][rfc-3986-21]). For example, a space character would be encoded with `%20`. @@ -64,8 +64,7 @@ consistent with how libcurl (and therefore Git) operates. The `http_proxy` variable exists only in the lowercase variant and libcurl does _not_ consider any uppercase form. _GCM also reflects this behavior._ -See -for more information. +See [the curl docs][curl-proxy-env-vars] for more information. ### Bypassing addresses @@ -73,13 +72,13 @@ In some circumstances you may wish to bypass a configured proxy for specific addresses. GCM supports the cURL environment variable `no_proxy` (and `NO_PROXY`) for this scenario, as does Git itself. -Like with the [other cURL proxy environment variables](#other-proxy-options), +Like with the [other cURL proxy environment variables][other-proxy-options], the lowercase variant will take precedence over the uppercase form. This environment variable should contain a comma-separated or space-separated list of host names that should not be proxied (should connect directly). -GCM attempts to match [libcurl's behaviour](https://curl.se/libcurl/c/CURLOPT_NOPROXY.html), +GCM attempts to match [libcurl's behaviour][curlopt-noproxy], which is briefly summarized here: - a value of `*` disables proxying for all hosts; @@ -114,24 +113,24 @@ $ git clone https://ghe.example.com/john.doe/myrepo fatal: The remote certificate is invalid according to the validation procedure. ``` -The **recommended and safest option** is to acquire a TLS certificate signed by a public trusted certificate authority (CA). There are multiple public CAs; here is a non-exhaustive list to consider: [Let's Encrypt](https://letsencrypt.org/), [Comodo](https://www.comodoca.com/), [Digicert](https://www.digicert.com/), [GoDaddy](https://www.godaddy.com/), [GlobalSign](https://www.globalsign.com). +The **recommended and safest option** is to acquire a TLS certificate signed by a public trusted certificate authority (CA). There are multiple public CAs; here is a non-exhaustive list to consider: [Let's Encrypt][lets-encrypt], [Comodo][comodo], [Digicert][digicert], [GoDaddy][godaddy], [GlobalSign][globalsign]. -If it is not possible to **obtain a TLS certificate from a trusted 3rd party** then you should try to add the _specific_ self-signed certificate or one of the CA certificates in the verification chain to your operating system's trusted certificate store ([macOS](https://support.apple.com/en-gb/guide/keychain-access/kyca2431/mac), [Windows](https://blogs.technet.microsoft.com/sbs/2008/05/08/installing-a-self-signed-certificate-as-a-trusted-root-ca-in-windows-vista/)). +If it is not possible to **obtain a TLS certificate from a trusted 3rd party** then you should try to add the _specific_ self-signed certificate or one of the CA certificates in the verification chain to your operating system's trusted certificate store ([macOS][mac-keychain-access], [Windows][install-cert-vista]). If you are _unable_ to either **obtain a trusted certificate**, or trust the self-signed certificate you can disable certificate verification in Git and GCM. --- **Security Warning** :warning: -Disabling verification of TLS (SSL) certificates removes protection against a [man-in-the-middle (MITM) attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). +Disabling verification of TLS (SSL) certificates removes protection against a [man-in-the-middle (MITM) attack][mitm-attack]. Only disable certificate verification if you are sure you need to, are aware of all the risks, and are unable to trust specific self-signed certificates (as described above). --- -The [environment variable `GIT_SSL_NO_VERIFY`](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_networking) and [Git configuration option `http.sslVerify`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpsslVerify) can be used to control TLS (SSL) certificate verification. +The [environment variable `GIT_SSL_NO_VERIFY`][git-ssl-no-verify] and [Git configuration option `http.sslVerify`][git-http-ssl-verify] can be used to control TLS (SSL) certificate verification. -To disable verification for a specific remote (for example ): +To disable verification for a specific remote (for example `https://example.com`): ```shell git config --global http.https://example.com.sslVerify false @@ -152,4 +151,26 @@ git config --global http.sslVerify false --- -**Note:** You may also experience similar verification errors if you are using a network traffic inspection tool such as [Telerik Fiddler](https://www.telerik.com/fiddler). If you are using such tools please consult their documentation for trusting the proxy root certificates. +**Note:** You may also experience similar verification errors if you are using a network traffic inspection tool such as [Telerik Fiddler][telerik-fiddler]. If you are using such tools please consult their documentation for trusting the proxy root certificates. + +[environment]: environment.md +[configuration]: configuration.md +[git-http-proxy]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy +[git-remote-name-proxy]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-remoteltnamegtproxy +[rfc-3986-321]: https://tools.ietf.org/html/rfc3986#section-3.2.1 +[rfc-3986-22]: https://tools.ietf.org/html/rfc3986#section-2.2 +[rfc-3986-21]: https://tools.ietf.org/html/rfc3986#section-2.1 +[curl-proxy-env-vars]: https://everything.curl.dev/usingcurl/proxies#proxy-environment-variables +[other-proxy-options]: #other-proxy-options +[curlopt-noproxy]: https://curl.se/libcurl/c/CURLOPT_NOPROXY.html +[lets-encrypt]: https://letsencrypt.org/ +[comodo]: https://www.comodoca.com/ +[digicert]: https://www.digicert.com/ +[godaddy]: https://www.godaddy.com/ +[globalsign]: https://www.globalsign.com +[mac-keychain-access]: https://support.apple.com/en-gb/guide/keychain-access/kyca2431/mac +[install-cert-vista]: https://blogs.technet.microsoft.com/sbs/2008/05/08/installing-a-self-signed-certificate-as-a-trusted-root-ca-in-windows-vista/ +[mitm-attack]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack +[git-ssl-no-verify]: https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables#_networking +[git-http-ssl-verify]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpsslVerify +[telerik-fiddler]: https://www.telerik.com/fiddler diff --git a/docs/usage.md b/docs/usage.md index 1f64cbd1a..1a3b1e89b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -23,7 +23,7 @@ Displays the current version. Commands for interaction with Git. You shouldn't need to run these manually. -Read the [Git manual](https://git-scm.com/docs/gitcredentials#_custom_helpers) about custom helpers for more information. +Read the [Git manual][git-credentials-custom-helpers] about custom helpers for more information. ### configure/unconfigure @@ -36,4 +36,7 @@ Set your user-level Git configuration (`~/.gitconfig`) to use GCM. If you pass Interact with the Azure Repos host provider to bind/unbind user accounts to Azure DevOps organizations or specific remote URLs, and manage the authentication authority cache. -For more information about managing user account bindings see [here](azrepos-users-and-tokens.md#useraccounts). +For more information about managing user account bindings see [here][azure-access-tokens-ua]. + +[azure-access-tokens-ua]: azrepos-users-and-tokens.md#useraccounts +[git-credentials-custom-helpers]: https://git-scm.com/docs/gitcredentials#_custom_helpers diff --git a/docs/windows-broker.md b/docs/windows-broker.md index 62b422ee5..79190ea72 100644 --- a/docs/windows-broker.md +++ b/docs/windows-broker.md @@ -1,21 +1,21 @@ # Web Account Manager integration -Git Credential Manager (GCM) knows how to integrate with the [Web Account Manager (WAM)](https://docs.microsoft.com/azure/active-directory/devices/concept-primary-refresh-token#key-terminology-and-components) feature of Windows. +Git Credential Manager (GCM) knows how to integrate with the [Web Account Manager (WAM)][azure-refresh-token-terms] feature of Windows. GCM uses WAM to store credentials for Azure DevOps. Authentication requests are said to be "brokered" to the operating system. Currently, GCM will share authentication state with a few other Microsoft developer tools like Visual Studio and the Azure CLI, meaning fewer authentication prompts. -Enabling WAM integration may also be required with certain [Conditional Access policies](https://docs.microsoft.com/azure/active-directory/conditional-access/overview), which enterprises use to help protect their assets, including source code. +Enabling WAM integration may also be required with certain [Conditional Access policies][azure-conditional-access], which enterprises use to help protect their assets, including source code. Integration with the WAM broker offers convenience and other benefits, but may also make unexpected other changes on your device. On a device owned and managed by your institution or employer, WAM is probably the right choice. On a personal device or a device owned by a different institution (e.g. if you're a contractor working for Company A with access to resources at Company B), there are surprising behaviors that you should be aware of before enabling WAM integration. -Note that this only affects [Azure DevOps](https://dev.azure.com). +Note that this only affects [Azure DevOps][azure-devops]. It doesn't impact authentication with GitHub, Bitbucket, or any other Git host. ## How to enable -You can opt-in to WAM support by setting the environment variable [`GCM_MSAUTH_USEBROKER`](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/environment.md#gcm_msauth_usebroker-experimental) or setting the Git configuration value [`credential.msauthUseBroker`](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/configuration.md#credentialmsauthusebroker-experimental). +You can opt-in to WAM support by setting the environment variable [`GCM_MSAUTH_USEBROKER`][GCM_MSAUTH_USEBROKER] or setting the Git configuration value [`credential.msauthUseBroker`][credential.msauthUseBroker]. ## Features @@ -37,16 +37,16 @@ When you sign into an Azure DevOps organization backed by Azure AD (often your c If your machine isn't Azure AD-joined, or is Azure AD-joined to a different tenant, WAM will present you with a dialog box suggesting you stay signed in and allow the organization to manage your device. The dialog box has changed a bit in various versions of Windows; here are two examples from 2021: -![Consent dialog pre-21H1](img/aad-questions.png) +![Consent dialog pre-21H1][aad-questions] -![Consent dialog post-21H1](img/aad-questions-21H1.png) +![Consent dialog post-21H1][aad-questions-21h1] Depending on what you click, one of three things can happen: - If you leave "allow my organization to manage my device" checked and click "OK", your computer will be registered with the Azure AD tenant backing the organization. It may also be MDM-enrolled ("Mobile Device Management" -- think Intune, AirWatch, MobileIron, etc.), meaning an administrator can deploy policies to your machine: requiring certain kinds of sign-in, turning on antivirus and firewall software, and enabling BitLocker. Your identity will also be available to other apps on the computer for signing in, some of which may do so automatically. -![Example of policies pushed to an Intune-enrolled device](img/aad-bitlocker.png) +![Example of policies pushed to an Intune-enrolled device][aad-bitlocker] - If you uncheck "allow my organization to manage my device" and click "OK", your computer will be registered with Azure AD but will not be MDM-enrolled. Your identity will be available to other apps on the computer for signing in. Other apps may log you in automatically or prompt you again to allow your organization to manage your device. @@ -55,16 +55,16 @@ If so, you'll be prompted with instructions on how to enroll in MDM. - If you instead click "No, sign in to this app only", your machine will not be joined to Azure AD or MDM-enrolled, so no policies can be enforced, and your identity won't be made available to other apps on the computer. Similar to the above, your organization's Conditional Access policies may prevent you from proceeding. -If Conditional Access is required to access your organization's Git repositories, you can [enable WAM integration](environment.md#GCM_MSAUTH_USEBROKER-experimental) (or follow other instructions your organization provides). +If Conditional Access is required to access your organization's Git repositories, you can [enable WAM integration][GCM_MSAUTH_USEBROKER] (or follow other instructions your organization provides). #### Removing device management If you've allowed your computer to be managed and want to undo it, you can go into **Settings**, **Accounts**, **Access work or school**. In the section where you see your email address and organization name, click **Disconnect**. -![Finding your work or school account](img/aad-work-school.png) +![Finding your work or school account][aad-work-school] -![Disconnecting from Azure AD](img/aad-disconnect.png) +![Disconnecting from Azure AD][aad-disconnect] ### For Microsoft accounts @@ -74,14 +74,14 @@ In order to sign in with an MSA you should continue and select "Use a different This is due to a configuration outside of our control. We expect this experience to improve over time and a "personal account" option to be presented in the future. -![Initial dialog to choose an existing or different account](img/get-signed-in.png) +![Initial dialog to choose an existing or different account][ms-sign-in] If you've connected your MSA to Windows or signed-in to other Microsoft applications such as Office, then you may see this account listed in the authentication prompts when using GCM. For any connected MSA, you can control whether or not the account is available to other Microsoft applications in **Settings**, **Accounts**, **Emails & accounts**: -![Allow all Microsoft apps to access your identity](img/all-microsoft.png) +![Allow all Microsoft apps to access your identity][all-ms-apps] -![Microsoft apps must ask to access your identity](img/apps-must-ask.png) +![Microsoft apps must ask to access your identity][apps-must-ask] Two very important things to note: @@ -92,8 +92,8 @@ As far as we can tell, there are no workarounds for either of these behaviors (o ## Running as administrator -The Windows broker ("WAM") makes heavy use of [COM](https://docs.microsoft.com/en-us/windows/win32/com/the-component-object-model), a remote procedure call (RPC) technology built into Windows. -In order to integrate with WAM, Git Credential Manager and the underlying [Microsoft Authentication Library (MSAL)](https://aka.ms/msal-net) must use COM interfaces and RPCs. +The Windows broker ("WAM") makes heavy use of [COM][ms-com], a remote procedure call (RPC) technology built into Windows. +In order to integrate with WAM, Git Credential Manager and the underlying [Microsoft Authentication Library (MSAL)][msal-dotnet] must use COM interfaces and RPCs. When you run Git Credential Manager as an elevated process, some of the calls made between GCM and WAM may fail due to differing process security levels. This can happen when you run `git` from an Administrator command-prompt or perform Git operations from Visual Studio running as Administrator. @@ -116,7 +116,23 @@ In order to fix the problem, there are a few options: 1. Run Git or Git Credential Manager from non-elevated processes. 2. Disable the broker by setting the - [`GCM_MSAUTH_USEBROKER`](environment.md#gcm_msauth_usebroker) + [`GCM_MSAUTH_USEBROKER`][GCM_MSAUTH_USEBROKER] environment variable or the - [`credential.msauthUseBroker`](configuration.md#credentialmsauthusebroker) + [`credential.msauthUseBroker`][credential.msauthUseBroker] Git configuration setting to `false`. + +[azure-refresh-token-terms]: https://docs.microsoft.com/azure/active-directory/devices/concept-primary-refresh-token#key-terminology-and-components +[azure-conditional-access]: https://docs.microsoft.com/azure/active-directory/conditional-access/overview +[azure-devops]: https://dev.azure.com +[GCM_MSAUTH_USEBROKER]: environment.md#GCM_MSAUTH_USEBROKER +[credential.msauthUseBroker]: configuration.md#credentialmsauthusebroker +[aad-questions]: img/aad-questions.png +[aad-questions-21h1]: img/aad-questions-21H1.png +[aad-bitlocker]: img/aad-bitlocker.png +[aad-work-school]: img/aad-work-school.png +[aad-disconnect]: img/aad-disconnect.png +[ms-sign-in]: img/get-signed-in.png +[all-ms-apps]: img/all-microsoft.png +[apps-must-ask]: img/apps-must-ask.png +[ms-com]: https://docs.microsoft.com/en-us/windows/win32/com/the-component-object-model +[msal-dotnet]: https://aka.ms/msal-net diff --git a/docs/wsl.md b/docs/wsl.md index 35e2c6bf7..d9e298ee5 100644 --- a/docs/wsl.md +++ b/docs/wsl.md @@ -1,7 +1,7 @@ # Windows Subsystem for Linux (WSL) GCM can be used with the -[Windows Subsystem for Linux (WSL)](https://aka.ms/wsl), both WSL1 and WSL2, by +[Windows Subsystem for Linux (WSL)][wsl], both WSL1 and WSL2, by following these instructions. In order to use GCM with WSL you must be on Windows 10 Version 1903 or later. @@ -12,11 +12,11 @@ It is highly recommended that you install Git for Windows to both install GCM and enable the best experience sharing credentials & settings between WSL and the Windows host. Alternatively, you must be using GCM version 2.0.XXX or later and configure the `WSLENV` environment variable as -[described below](#configuring-wsl-without-git-for-windows). +[described below][configuring-wsl-without-git-for-windows]. ## Configuring WSL with Git for Windows (recommended) -Start by installing the [latest Git for Windows ⬇️](https://github.com/git-for-windows/git/releases/latest) +Start by installing the [latest Git for Windows ⬇️][latest-git-for-windows] _Inside your WSL installation_, run the following command to set GCM as the Git credential helper: @@ -38,7 +38,7 @@ If you wish to use GCM inside of WSL _without installing Git for Windows_ you must complete additional configuration so that GCM can callback to Git inside of your WSL installation. -Start by installing the [latest GCM ⬇️](https://aka.ms/gcm/latest) +Start by installing the [latest GCM ⬇️][latest-gcm] _Inside your WSL installation_, run the following command to set GCM as the Git credential helper: @@ -70,7 +70,7 @@ instead. ## How it works GCM leverages the built-in interoperability between Windows and WSL, provided by -Microsoft. You can read more about Windows/WSL interop [here](https://docs.microsoft.com/en-us/windows/wsl/interop). +Microsoft. You can read more about Windows/WSL interop [here][wsl-interop]. Git inside of a WSL installation can launch the GCM _Windows_ application transparently to acquire credentials. Running GCM as a Windows application @@ -93,7 +93,7 @@ as well as WSL Git as they are stored in different files (`%USERPROFILE%\.gitconfig` vs `\\wsl$\distro\home\$USER\.gitconfig`). You can configure WSL such that GCM will use the WSL Git configuration following -the [instructions above](#configuring-wsl-without-git-for-windows). However, +the [instructions above][configuring-wsl-without-git-for-windows]. However, this then means that things like proxy settings are unique to the specific WSL installation, and not shared with others or the Windows host. @@ -102,8 +102,15 @@ installation, and not shared with others or the Windows host. Yes. Rather than install GCM as a Windows application (and have WSL Git invoke the Windows GCM), can you install GCM as a Linux application instead. -To do this, simply follow the [GCM installation instructions for Linux](../README.md#linux). +To do this, simply follow the [GCM installation instructions for Linux][linux-installation]. **Note:** In this scenario, because GCM is running as a Linux application it cannot utilize authentication or credential storage features of the host Windows operating system. + +[wsl]: https://aka.ms/wsl +[configuring-wsl-without-git-for-windows]: #configuring-wsl-without-git-for-windows +[latest-git-for-windows]: https://github.com/git-for-windows/git/releases/latest +[latest-gcm]: https://aka.ms/gcm/latest +[wsl-interop]: https://docs.microsoft.com/en-us/windows/wsl/interop +[linux-installation]: ../README.md#linux