diff --git a/.github/ISSUE_TEMPLATE/auth-problem.md b/.github/ISSUE_TEMPLATE/auth-problem.md index bb394b3ad..e3bb08de3 100644 --- a/.github/ISSUE_TEMPLATE/auth-problem.md +++ b/.github/ISSUE_TEMPLATE/auth-problem.md @@ -44,7 +44,9 @@ origin https://dev.azure.com/contoso/_git/widgets * [ ] https://`{org}`@dev.azure.com/`{org}`/... * [ ] https://`{org}`.visualstudio.com/... -**_[Azure DevOps only]_ If the account picker shows more than one identity as you authenticate, check that you selected the same one that has access on the web.** +**_[Azure DevOps only]_ If the account picker shows more than one identity as +you authenticate, check that you selected the same one that has access on the +web.** * [ ] Not applicable * [ ] I only see one identity @@ -58,13 +60,16 @@ I am authenticated and my Git operation completes successfully. **Actual behavior** -A clear and concise description of what happens. For example: exception is thrown, UI freezes, etc. +A clear and concise description of what happens. For example: exception is +thrown, UI freezes, etc. **Logs** -Set the environment variables `GCM_TRACE=1` and `GIT_TRACE=1` and re-run your Git command. Review and redact any private information and attach the log. +Set the environment variables `GCM_TRACE=1` and `GIT_TRACE=1` and re-run your +Git command. Review and redact any private information and attach the log. -If you are running inside of Windows Subsystem for Linux (WSL), you must also set an additional environment variable to enable tracing: `WSLENV=$WSLENV:GCM_TRACE`. +If you are running inside of Windows Subsystem for Linux (WSL), you must also +set an additional environment variable to enable tracing: `WSLENV=$WSLENV:GCM_TRACE`. For example: ```shell diff --git a/.github/ISSUE_TEMPLATE/experimental.md b/.github/ISSUE_TEMPLATE/experimental.md index db0b8ad21..fa867cbef 100644 --- a/.github/ISSUE_TEMPLATE/experimental.md +++ b/.github/ISSUE_TEMPLATE/experimental.md @@ -44,7 +44,9 @@ origin https://dev.azure.com/contoso/_git/widgets * [ ] https://`{org}`@dev.azure.com/`{org}`/... * [ ] https://`{org}`.visualstudio.com/... -**_[Azure DevOps only]_ If the account picker shows more than one identity as you authenticate, check that you selected the same one that has access on the web.** +**_[Azure DevOps only]_ If the account picker shows more than one identity as +you authenticate, check that you selected the same one that has access on the +web.** * [ ] Not applicable * [ ] I only see one identity @@ -58,13 +60,16 @@ I am authenticated and my Git operation completes successfully. **Actual behavior** -A clear and concise description of what happens. For example: exception is thrown, UI freezes, etc. +A clear and concise description of what happens. For example: exception is +thrown, UI freezes, etc. **Logs** -Set the environment variables `GCM_TRACE=1` and `GIT_TRACE=1` and re-run your Git command. Review and redact any private information and attach the log. +Set the environment variables `GCM_TRACE=1` and `GIT_TRACE=1` and re-run your +Git command. Review and redact any private information and attach the log. -If you are running inside of Windows Subsystem for Linux (WSL), you must also set an additional environment variable to enable tracing: `WSLENV=$WSLENV:GCM_TRACE`. +If you are running inside of Windows Subsystem for Linux (WSL), you must also +set an additional environment variable to enable tracing: `WSLENV=$WSLENV:GCM_TRACE`. For example: ```shell diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc index 6e0ac4ada..508340a6b 100644 --- a/.markdownlint.jsonc +++ b/.markdownlint.jsonc @@ -1,6 +1,11 @@ // For information on writing markdownlint configuration see: // https://github.com/DavidAnson/markdownlint/blob/main/README.md#optionsconfig { - "MD013": false, // Line length and line breaking convention not yet standardised across docs + "MD013": { + "line_length": 80, + "code_blocks": false, + "headings": false, + "tables": false + }, "MD024": false // The format for some files require repeated headings, e.g. "Example" } diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 46e9cffc1..8542fcb6f 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -67,8 +67,8 @@ members of the project's leadership. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][cc-homepage], version 1.4, -available at [Contributor Covenant Code of Conduct][cc-coc]. +This Code of Conduct is adapted from the [Contributor Covenant][cc-homepage], +version 1.4, 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] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fad3f4f95..fdf9b2f15 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,19 @@ # Contributing -Hi there! We're thrilled that you'd like to contribute to GCM :tada:. Your help is essential for keeping it great. +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][contribute-under-repo-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. +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. ## Start with an issue 1. Open an [issue][issue] to discuss the change you want to see. -This helps us coordinate and reduce duplication. + This helps us coordinate and reduce duplication. 1. Once we've had some discussion, you're ready to code! ## Submitting a pull request @@ -19,20 +23,25 @@ This helps us coordinate and reduce duplication. 1. Make sure the tests pass on your machine: `dotnet test` 1. Create a new branch: `git switch -c my-branch-name` 1. Make your change, add tests, and make sure the tests still pass -1. For UI updates, test your changes by executing a `dotnet run` in applicable UI-related project directories: +1. For UI updates, test your changes by executing a `dotnet run` in applicable + UI-related project directories: - `Atlassian.Bitbucket.UI.Avalonia` - `GitHub.UI.Avalonia` - `Atlassian.Bitbucket.UI.Windows` - `GitHub.UI.Windows` 1. Organize your changes into one or more [logical, descriptive commits][commits]. 1. Push to your fork and [submit a pull request][pr] -1. Pat your self on the back and wait for your pull request to be reviewed and merged. +1. Pat your self on the back and wait for your pull request to be reviewed and + merged. -Here are a few things you can do that will increase the likelihood of your pull request being accepted: +Here are a few things you can do that will increase the likelihood of your pull +request being accepted: - Match existing code style. - Write tests. -- Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests. +- Keep your change as focused as possible. If there are multiple changes you + would like to make that are not dependent upon each other, consider + submitting them as separate pull requests. ## Resources diff --git a/README.md b/README.md index 6cc051c90..a97a7b79d 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,25 @@ --- -[Git Credential Manager][gcm] (GCM) is a secure Git credential helper built on [.NET][dotnet] 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][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. +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][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. +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: +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][azure-devops-ssh] - [GitHub SSH][github-ssh] @@ -34,7 +44,10 @@ Proxy support|✓|✓|✓ `arm64` support|best effort|✓|best effort, no packages `armhf` support|_N/A_|_N/A_|best effort, no packages -(\*) GCM guarantees support for the below Linux distributions. GCM maintainers also monitor and evaluate issues opened against other distributions to determine community interest/engagement and whether an emerging platform should become fully-supported. +(\*) GCM guarantees support for the below Linux distributions. GCM maintainers +also monitor and evaluate issues opened against other distributions to determine +community interest/engagement and whether an emerging platform should become +fully-supported. - Debian/Ubuntu/Linux Mint - Fedora/CentOS/RHEL @@ -44,7 +57,8 @@ Proxy support|✓|✓|✓ ### macOS Homebrew -The preferred installation mechanism is using Homebrew; we offer a Cask in our custom Tap. +The preferred installation mechanism is using Homebrew; we offer a Cask in our +custom Tap. To install, run the following: @@ -61,7 +75,9 @@ brew upgrade git-credential-manager-core #### Git Credential Manager for Mac and Linux (Java-based GCM) -If you have an existing installation of the 'Java GCM' on macOS and you have installed this using Homebrew, this installation will be unlinked (`brew unlink git-credential-manager`) when GCM is installed. +If you have an existing installation of the 'Java GCM' on macOS and you have +installed this using Homebrew, this installation will be unlinked +(`brew unlink git-credential-manager`) when GCM is installed. #### Uninstall @@ -75,7 +91,8 @@ brew uninstall --cask git-credential-manager-core ### macOS Package -We also provide a [.pkg installer][latest-release] 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 @@ -159,43 +176,55 @@ To uninstall: [Follow these instructions][linux-uninstall] for your distribution. -**Note:** all Linux distributions [require additional configuration][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][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. +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][git-for-windows-screenshot] #### Standalone installation -You can also download the [latest installer][latest-release] for Windows to install GCM standalone. +You can also download the [latest installer][latest-release] for Windows to +install GCM standalone. **:warning: Important :warning:** -Installing GCM as a standalone package on Windows will forcibly override the version of GCM that is bundled with Git for Windows, **even if the version bundled with Git for Windows is a later version**. +Installing GCM as a standalone package on Windows will forcibly override the +version of GCM that is bundled with Git for Windows, **even if the version +bundled with Git for Windows is a later version**. There are two flavors of standalone installation on Windows: - User (preferred) (`gcmuser-win*`): - Does not require administrator rights. Will install only for the current user and updates only the current user's Git configuration. + Does not require administrator rights. Will install only for the current user + and updates only the current user's Git configuration. - System (`gcm-win*`): - Requires administrator rights. Will install for all users on the system and update the system-wide Git configuration. + Requires administrator rights. Will install for all users on the system and + update the system-wide Git configuration. -To install, double-click the desired installation package and follow the instructions presented. +To install, double-click the desired installation package and follow the +instructions presented. #### Uninstall (Windows 10) -To uninstall, open the Settings app and navigate to the Apps section. Select "Git Credential Manager" and click "Uninstall". +To uninstall, open the Settings app and navigate to the Apps section. Select +"Git Credential Manager" and click "Uninstall". #### Uninstall (Windows 7-8.1) -To uninstall, open Control Panel and navigate to the Programs and Features screen. Select "Git Credential Manager" and click "Remove". +To uninstall, open Control Panel and navigate to the Programs and Features +screen. Select "Git Credential Manager" and click "Remove". #### Windows Subsystem for Linux (WSL) @@ -218,16 +247,21 @@ 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`][gcm-commit-12294990] - of the Git project, and released in Git 2.27.0. + 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][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. +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][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][gcm-usage]. @@ -264,7 +298,8 @@ This project follows [GitHub's Open Source Code of Conduct][gcm-coc]. ## License We're [MIT][gcm-license] licensed. -When using GitHub logos, please be sure to follow the [GitHub logo guidelines][github-logos]. +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 diff --git a/SECURITY.md b/SECURITY.md index e9a6244a3..994a657e2 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,7 @@ # Security -If you discover a security issue in this repo, please submit it through the [GitHub Security Bug Bounty][hackerone-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. diff --git a/docs/autodetect.md b/docs/autodetect.md index 954617da1..5f1390f72 100644 --- a/docs/autodetect.md +++ b/docs/autodetect.md @@ -18,8 +18,8 @@ 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][explicit-config] -GCM to use a particular provider. +If a heuristic matches incorrectly, you can always +[explicitly configure][explicit-config] GCM to use a particular provider. ## Remote URL probing @@ -28,8 +28,9 @@ 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-config] -the host provider for your self-hosted instance. +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`][credential-provider] configuration entry @@ -39,8 +40,8 @@ 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`][gcm-autodetect-timeout] -environment variable, or the [`credential.autoDetectTimeout`][credential-autoDetectTimeout] +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,9 +53,9 @@ 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`][gcm-provider] -environment variable, or the [`credential.provider`][credential-provider] -Git configuration setting for this purpose. +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 "ghe.example.com" hostname, you can run the following command: diff --git a/docs/bitbucket-development.md b/docs/bitbucket-development.md index e9cef3b56..1074e756e 100644 --- a/docs/bitbucket-development.md +++ b/docs/bitbucket-development.md @@ -1,85 +1,127 @@ # Bitbucket Authentication, 2FA and OAuth -By default for authenticating against private Git repositories Bitbucket supports SSH and username/password Basic Auth over HTTPS. -Username/password Basic Auth over HTTPS is also available for REST API access. -Additionally Bitbucket supports App-specific passwords which can be used via Basic Auth as username/app-specific-password. - -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][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][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][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. -Bitbucket's Access Token's expire after 1 hour if not revoked, as opposed to GitHub's that expire after 1 year. -When GitHub's Access Tokens expire the user must anticipate in the standard OAuth authentication flow to get a new Access Token. Since this occurs, in theory, once per year this is not too onerous. -Since Bitbucket's Access Tokens expire every hour it is too much to expect a user to go through the OAuth authentication flow every hour. -Bitbucket implements refresh Tokens. -Refresh Tokens are issued to the client application at the same time as Access Tokens. -They can only be used to request a new Access Token, and then only if they have not been revoked. -As such the support for Bitbucket and the use of its OAuth in the Git Credentials Manager differs significantly from how VSTS and GitHub are implemented. -This is explained in more detail below. +By default for authenticating against private Git repositories Bitbucket +supports SSH and username/password Basic Auth over HTTPS. Username/password +Basic Auth over HTTPS is also available for REST API access. Additionally +Bitbucket supports App-specific passwords which can be used via Basic Auth as +username/app-specific-password. + +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][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][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][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. Bitbucket's Access Token's +expire after 1 hour if not revoked, as opposed to GitHub's that expire after 1 +year. When GitHub's Access Tokens expire the user must anticipate in the +standard OAuth authentication flow to get a new Access Token. Since this occurs, +in theory, once per year this is not too onerous. Since Bitbucket's Access +Tokens expire every hour it is too much to expect a user to go through the OAuth +authentication flow every hour.Bitbucket implements refresh Tokens. +Refresh Tokens are issued to the client application at the same time as Access +Tokens. They can only be used to request a new Access Token, and then only if +they have not been revoked. As such the support for Bitbucket and the use of its +OAuth in the Git Credentials Manager differs significantly from how VSTS and +GitHub are implemented. 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][wincred-manager] 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. +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. ## Authentication User Experience -When the GCM is triggered by Git, the GCM will check the `host` parameter passed to it. -If it contains `bitbucket.org` it will trigger the Bitbucket related processes. +When the GCM is triggered by Git, the GCM will check the `host` parameter passed +to it. If it contains `bitbucket.org` it will trigger the Bitbucket related +processes. ### Basic Authentication -If the GCM needs to prompt the user for credentials they will always be shown an initial dialog where they can enter a username and password. If the `username` parameter was passed into the GCM it is used to pre-populate the username field, although it can be overridden. -When username and password credentials are submitted the GCM will use them to attempt to retrieve a token, for Basic Authentication this token is in effect the password the user just entered. -The GCM retrieves this `token` by checking the password can be used to successfully retrieve the User profile via the Bitbucket REST API. - -If the username and password credentials sent as Basic Authentication credentials works, then the password is identified as the token. The credentials, the username and the password/token, are then stored and the values returned to Git. - -If the request for the User profile via the REST API fails with a 401 return code it indicates the username/password combination is invalid, nothing is stored and nothing is returned to Git. - -However if the request fails with a 403 (Forbidden) return code, this indicates that the username and password are valid but 2FA is enabled on the Bitbucket Account. -When this occurs the user it prompted to complete the OAuth authentication process. +If the GCM needs to prompt the user for credentials they will always be shown an +initial dialog where they can enter a username and password. If the `username` +parameter was passed into the GCM it is used to pre-populate the username field, +although it can be overridden. When username and password credentials are +submitted the GCM will use them to attempt to retrieve a token, for Basic +Authentication this token is in effect the password the user just entered. The +GCM retrieves this `token` by checking the password can be used to successfully +retrieve the User profile via the Bitbucket REST API. + +If the username and password credentials sent as Basic Authentication +credentials works, then the password is identified as the token. The +credentials, the username and the password/token, are then stored and the values +returned to Git. + +If the request for the User profile via the REST API fails with a 401 return +code it indicates the username/password combination is invalid, nothing is +stored and nothing is returned to Git. + +However if the request fails with a 403 (Forbidden) return code, this indicates +that the username and password are valid but 2FA is enabled on the Bitbucket +Account. When this occurs the user it prompted to complete the OAuth +authentication process. ### OAuth -OAuth authentication prompts the User with a new dialog where they can trigger OAuth authentication. -This involves opening a browser request to `_https://bitbucket.org/site/oauth2/authorize?response_type=code&client_id={consumerkey}&state=authenticated&scope={scopes}&redirect_uri=http://localhost:34106/_`. -This will trigger a flow on Bitbucket where the user must login, potentially including a 2FA prompt, and authorize the GCM to access Bitbucket with the specified scopes. -The GCM will spawn a temporary, local webserver, listening on port 34106, to handle the OAuth redirect/callback. -Assuming the user successfully logins into Bitbucket and authorizes the GCM this callback will include the Access and Refresh Tokens. +OAuth authentication prompts the User with a new dialog where they can trigger +OAuth authentication. This involves opening a browser request to `_https://bitbucket.org/site/oauth2/authorize?response_type=code&client_id={consumerkey}&state=authenticated&scope={scopes}&redirect_uri=http://localhost:34106/_`. +This will trigger a flow on Bitbucket where the user must login, potentially +including a 2FA prompt, and authorize the GCM to access Bitbucket with the +specified scopes. The GCM will spawn a temporary, local webserver, listening on +port 34106, to handle the OAuth redirect/callback. Assuming the user +successfully logins into Bitbucket and authorizes the GCM this callback will +include the Access and Refresh Tokens. -The Access and Refresh Tokens will be stored against the username and the username/Access Token credentials returned to Git. +The Access and Refresh Tokens will be stored against the username and the +username/Access Token credentials returned to Git. ## 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][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][bitbucket]. -As far as GCMC is concerned the main difference it doesn't support OAuth so only Basic Authentication is available. +As far as GCMC is concerned the main difference it doesn't support OAuth so only +Basic Authentication is available. -It is possible to test with Bitbucket Server by running it locally using the following command from the Atlassian SDK: +It is possible to test with Bitbucket Server by running it locally using the +following command from the Atlassian SDK: ❯ atlas-run-standalone --product bitbucket 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 +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][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/ diff --git a/docs/configuration.md b/docs/configuration.md index 94393c3ea..656169691 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,22 +2,40 @@ [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. +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. -Global configuration settings override system configuration settings, and local configuration settings override global settings; and because the configuration details exist within Git's configuration files you can use Git's `git config` utility to set, unset, and alter the setting values. All of GCM's configuration settings begin with the term `credential`. +Global configuration settings override system configuration settings, and local +configuration settings override global settings; and because the configuration +details exist within Git's configuration files you can use Git's `git config` +utility to set, unset, and alter the setting values. All of GCM's configuration +settings begin with the term `credential`. -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. +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][envars] **which take precedence over configuration options**. System administrators may also configure [default values][enterprise-config] 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. +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. **Example:** -> `credential.microsoft.visualstudio.com.namespace` is more specific than `credential.visualstudio.com.namespace`, which is more specific than `credential.namespace`. +> `credential.microsoft.visualstudio.com.namespace` is more specific than +> `credential.visualstudio.com.namespace`, which is more specific than +> `credential.namespace`. -In the examples above, the `credential.namespace` setting would affect any remote repository; the `credential.visualstudio.com.namespace` would affect any remote repository in the domain, and/or any subdomain (including `www.`) of, 'visualstudio.com'; where as the `credential.microsoft.visualstudio.com.namespace` setting would only be applied to remote repositories hosted at 'microsoft.visualstudio.com'. +In the examples above, the `credential.namespace` setting would affect any +remote repository; the `credential.visualstudio.com.namespace` would affect any +remote repository in the domain, and/or any subdomain (including `www.`) of, +'visualstudio.com'; where as the +`credential.microsoft.visualstudio.com.namespace` setting would only be applied +to remote repositories hosted at 'microsoft.visualstudio.com'. For the complete list of settings GCM understands, see the list below. @@ -25,16 +43,20 @@ For the complete list of settings GCM understands, see the list below. ### credential.interactive -Permit or disable GCM from interacting with the user (showing GUI or TTY prompts). If interaction is required but has been disabled, an error is returned. +Permit or disable GCM from interacting with the user (showing GUI or TTY +prompts). If interaction is required but has been disabled, an error is returned. -This can be helpful when using GCM in headless and unattended environments, such as build servers, where it would be preferable to fail than to hang indefinitely waiting for a non-existent user. +This can be helpful when using GCM in headless and unattended environments, such +as build servers, where it would be preferable to fail than to hang indefinitely +waiting for a non-existent user. To disable interactivity set this to `false` or `0`. #### Compatibility -In previous versions of GCM this setting had a different behavior and accepted other values. -The following table summarizes the change in behavior and the mapping of older values such as `never`: +In previous versions of GCM this setting had a different behavior and accepted +other values. The following table summarizes the change in behavior and the +mapping of older values such as `never`: Value(s)|Old meaning|New meaning -|-|- @@ -69,7 +91,9 @@ ID|Provider Automatic provider selection is based on the remote URL. -This setting is typically used with a scoped URL to map a particular set of remote URLs to providers, for example to mark a host as a GitHub Enterprise instance. +This setting is typically used with a scoped URL to map a particular set of +remote URLs to providers, for example to mark a host as a GitHub Enterprise +instance. #### Example @@ -83,11 +107,13 @@ git config --global credential.ghe.contoso.com.provider github ### credential.authority _(deprecated)_ -> This setting is deprecated and should be replaced by `credential.provider` with the corresponding provider ID value. +> This setting is deprecated and should be replaced by `credential.provider` +> with the corresponding provider ID value. > > 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. +Select the host provider to use when authenticating by which authority is +supported by the providers. Authority|Provider(s) -|- @@ -150,7 +176,9 @@ git config --global credential.autoDetectTimeout -1 ### credential.allowWindowsAuth -Allow detection of Windows Integrated Authentication (WIA) support for generic host providers. Setting this value to `false` will prevent the use of WIA and force a basic authentication prompt when using the Generic host provider. +Allow detection of Windows Integrated Authentication (WIA) support for generic +host providers. Setting this value to `false` will prevent the use of WIA and +force a basic authentication prompt when using the Generic host provider. **Note:** WIA is only supported on Windows. @@ -173,7 +201,8 @@ git config --global credential.tfsonprem123.allowWindowsAuth false ### credential.httpProxy _(deprecated)_ -> This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option][git-config-http-proxy]. +> This setting is deprecated and should be replaced by the +> [standard `http.proxy` Git configuration option][git-config-http-proxy]. > > See [HTTP Proxy][http-proxy] for more information. @@ -193,10 +222,12 @@ git config --global credential.httpsProxy http://john.doe:password@proxy.contoso ### credential.bitbucketAuthModes -Override the available authentication modes presented during Bitbucket authentication. -If this option is not set, then the available authentication modes will be automatically detected. +Override the available authentication modes presented during Bitbucket +authentication. If this option is not set, then the available authentication +modes will be automatically detected. -**Note:** This setting only applies to Bitbucket.org, and not Server or DC instances. +**Note:** This setting only applies to Bitbucket.org, and not Server or DC +instances. **Note:** This setting supports multiple values separated by commas. @@ -218,13 +249,20 @@ git config --global credential.bitbucketAuthModes "oauth,basic" ### credential.bitbucketAlwaysRefreshCredentials -Forces GCM to ignore any existing stored Basic Auth or OAuth access tokens and always run through the process to refresh the credentials before returning them to Git. +Forces GCM to ignore any existing stored Basic Auth or OAuth access tokens and +always run through the process to refresh the credentials before returning them +to Git. -This is especially relevant to OAuth credentials. Bitbucket.org access tokens expire after 2 hours, after that the refresh token must be used to get a new access token. +This is especially relevant to OAuth credentials. Bitbucket.org access tokens +expire after 2 hours, after that the refresh token must be used to get a new +access token. -Enabling this option will improve performance when using Oauth2 and interacting with Bitbucket.org if, on average, commits are done less frequently than every 2 hours. +Enabling this option will improve performance when using Oauth2 and interacting +with Bitbucket.org if, on average, commits are done less frequently than every +2 hours. -Enabling this option will decrease performance when using Basic Auth by requiring the user the re-enter credentials everytime. +Enabling this option will decrease performance when using Basic Auth by +requiring the user the re-enter credentials every time. Value|Refresh Credentials Before Returning -|- @@ -245,8 +283,9 @@ Defaults to false/disabled. ### credential.gitHubAuthModes -Override the available authentication modes presented during GitHub authentication. -If this option is not set, then the available authentication modes will be automatically detected. +Override the available authentication modes presented during GitHub +authentication. If this option is not set, then the available authentication +modes will be automatically detected. **Note:** This setting supports multiple values separated by commas. @@ -271,8 +310,9 @@ git config --global credential.gitHubAuthModes "oauth,basic" ### credential.gitLabAuthModes -Override the available authentication modes presented during GitLab authentication. -If this option is not set, then the available authentication modes will be automatically detected. +Override the available authentication modes presented during GitLab +authentication. If this option is not set, then the available authentication +modes will be automatically detected. **Note:** This setting supports multiple values separated by commas. @@ -295,8 +335,8 @@ git config --global credential.gitLabAuthModes "browser" ### credential.namespace -Use a custom namespace prefix for credentials read and written in the OS credential store. -Credentials will be stored in the format `{namespace}:{service}`. +Use a custom namespace prefix for credentials read and written in the OS +credential store. Credentials will be stored in the format `{namespace}:{service}`. Defaults to the value `git`. @@ -314,9 +354,11 @@ git config --global credential.namespace "my-namespace" 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. +Default value on Windows is `wincredman`, on macOS is `keychain`, and is unset +on Linux. -**Note:** See more information about configuring secret stores in [cred-stores][cred-stores]. +**Note:** See more information about configuring secret stores in +[cred-stores][cred-stores]. Value|Credential Store|Platforms -|-|- @@ -362,7 +404,8 @@ git config --global credential.cacheOptions "--timeout 300" ### credential.plaintextStorePath -Specify a custom directory to store plaintext credential files in when [`credential.credentialStore`][credential-credentialstore] 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`. @@ -378,7 +421,8 @@ git config --global credential.plaintextStorePath /mnt/external-drive/credential ### credential.dpapiStorePath -Specify a custom directory to store DPAPI protected credential files in when [`credential.credentialStore`][credential-credentialstore] 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`. @@ -394,7 +438,8 @@ git config --global credential.dpapiStorePath D:\credentials ### credential.msauthFlow -Specify which authentication flow should be used when performing Microsoft authentication and an interactive flow is required. +Specify which authentication flow should be used when performing Microsoft +authentication and an interactive flow is required. Defaults to `auto`. @@ -426,7 +471,9 @@ 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 [Windows Broker][wam] details for 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 -|- @@ -445,15 +492,23 @@ git config --global credential.msauthUseBroker true ### 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][use-http-path], 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`. -**Note:** GCM sets this value to `true` for `dev.azure.com` (Azure Repos) hosts after installation by default. +**Note:** GCM sets this value to `true` for `dev.azure.com` (Azure Repos) hosts +after installation by default. -This is because `dev.azure.com` alone is not enough information to determine the correct Azure authentication authority - we require a part of the path. The fallout of this is that for `dev.azure.com` remote URLs we do not support storing credentials against the full-path. We always store against the `dev.azure.com/org-name` stub. +This is because `dev.azure.com` alone is not enough information to determine the +correct Azure authentication authority - we require a part of the path. The +fallout of this is that for `dev.azure.com` remote URLs we do not support +storing credentials against the full-path. We always store against the +`dev.azure.com/org-name` stub. -In order to use Azure Repos and store credentials against a full-path URL, you must use the `org-name.visualstudio.com` remote URL format instead. +In order to use Azure Repos and store credentials against a full-path URL, you +must use the `org-name.visualstudio.com` remote URL format instead. Value|Git Behavior -|- @@ -462,7 +517,9 @@ Value|Git Behavior #### Example -On Windows using GitHub, for a user whose login is `alice`, and with `credential.useHttpPath` set to `false` (or not set), the following remote URLs will use the same credentials: +On Windows using GitHub, for a user whose login is `alice`, and with +`credential.useHttpPath` set to `false` (or not set), the following remote URLs +will use the same credentials: ```text Credential: "git:https://github.com" (user = alice) @@ -479,7 +536,8 @@ Credential: "git:https://bob@github.com" (user = bob) https://bob@github.com/example/myrepo ``` -Under the same user but with `credential.useHttpPath` set to `true`, these credentials would be used: +Under the same user but with `credential.useHttpPath` set to `true`, these +credentials would be used: ```text Credential: "git:https://github.com/foo/bar" (user = alice) diff --git a/docs/development.md b/docs/development.md index a8f88997a..dc45ef665 100644 --- a/docs/development.md +++ b/docs/development.md @@ -6,15 +6,18 @@ 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 the [.NET website][dotnet-web]. +You also need the latest version of the .NET SDK which can be downloaded and +installed from the [.NET website][dotnet-web]. ## Building -The `Git-Credential-Manager.sln` solution can be opened and built in Visual Studio, Visual Studio for Mac, Visual Studio Code, or JetBrains Rider. +The `Git-Credential-Manager.sln` solution can be opened and built in Visual +Studio, Visual Studio for Mac, Visual Studio Code, or JetBrains Rider. ### macOS -To build from inside an IDE, make sure to select the `MacDebug` or `MacRelease` solution configurations. +To build from inside an IDE, make sure to select the `MacDebug` or `MacRelease` +solution configurations. To build from the command line, run: @@ -28,7 +31,8 @@ The flat binaries can also be found in `out/osx/Installer.Mac/pkg/Debug/payload` ### Windows -To build from inside an IDE, make sure to select the `WindowsDebug` or `WindowsRelease` solution configurations. +To build from inside an IDE, make sure to select the `WindowsDebug` or +`WindowsRelease` solution configurations. To build from the command line, run: @@ -56,9 +60,12 @@ The flat binaries can also be found in `out/linux/Packaging.Linux/payload/Debug` ## Debugging -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 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][ioformat]: +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 @@ -67,7 +74,8 @@ host= ``` -..where `` is a supported hostname such as `github.com`, and `` is a line feed (or CRLF, we support both!). +..where `` is a supported hostname such as `github.com`, and `` is +a line feed (or CRLF, we support both!). You may also include the following optional fields, depending on your scenario: @@ -76,17 +84,23 @@ username= password= ``` -For more information about how Git interacts with credential helpers, please read Git's documentation on [custom helpers][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 -If you want to debug an already running GCM process, set the `GCM_DEBUG` environment variable to `1` or `true`. The process will wait on launch for a debugger to attach before continuing. +If you want to debug an already running GCM process, set the `GCM_DEBUG` +environment variable to `1` or `true`. The process will wait on launch for a +debugger to attach before continuing. -This is useful when debugging interactions between GCM and Git, and you want Git to be the one launching us. +This is useful when debugging interactions between GCM and Git, and you want +Git to be the one launching us. ### Collect trace output -If you want to debug a release build or installation of GCM, you can set the `GCM_TRACE` environment variable to `1` to print trace information to standard error, or to an absolute file path to write trace information to a file. +If you want to debug a release build or installation of GCM, you can set the +`GCM_TRACE` environment variable to `1` to print trace information to standard +error, or to an absolute file path to write trace information to a file. For example: @@ -98,7 +112,8 @@ $ GCM_TRACE=1 git-credential-manager-core version ### Code coverage metrics -If you want code coverage metrics these can be generated either from the command line: +If you want code coverage metrics these can be generated either from the command +line: ```shell dotnet test --collect:"XPlat Code Coverage" --settings=./.code-coverage/coverlet.settings.xml @@ -110,7 +125,8 @@ Or via the VSCode Terminal/Run Task: test with coverage ``` -HTML reports can be generated using ReportGenerator, this should be installed during the build process, from the command line: +HTML reports can be generated using ReportGenerator, this should be installed +during the build process, from the command line: ```shell dotnet ~/.nuget/packages/reportgenerator/*/*/net6.0/ReportGenerator.dll -reports:./**/TestResults/**/coverage.cobertura.xml -targetdir:./out/code-coverage diff --git a/docs/environment.md b/docs/environment.md index 36372640c..cb70baf27 100644 --- a/docs/environment.md +++ b/docs/environment.md @@ -1,17 +1,22 @@ # Environment variables -[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] 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] options and enterprise system administrator [default values][default-values]**. +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. +For the complete list of environment variables GCM understands, see the list +below. ## Available settings ### GCM_TRACE Enables trace logging of all activities. -Configuring Git and GCM to trace to the same location is often desirable, and GCM is compatible and cooperative with `GIT_TRACE`. +Configuring Git and GCM to trace to the same location is often desirable, and +GCM is compatible and cooperative with `GIT_TRACE`. #### Example @@ -29,7 +34,8 @@ export GIT_TRACE=$HOME/git.log export GCM_TRACE=$HOME/git.log ``` -If the value of `GCM_TRACE` is a full path to a file in an existing directory, logs are appended to the file. +If the value of `GCM_TRACE` is a full path to a file in an existing directory, +logs are appended to the file. If the value of `GCM_TRACE` is `true` or `1`, logs are written to standard error. @@ -41,8 +47,8 @@ _No configuration equivalent._ ### GCM_TRACE_SECRETS -Enables tracing of secret and sensitive information, which is by default masked in trace output. -Requires that `GCM_TRACE` is also enabled. +Enables tracing of secret and sensitive information, which is by default masked +in trace output. Requires that `GCM_TRACE` is also enabled. #### Example @@ -60,7 +66,8 @@ export GCM_TRACE=$HOME/gcm.log export GCM_TRACE_SECRETS=1 ``` -If the value of `GCM_TRACE_SECRETS` is `true` or `1`, trace logs will include secret information. +If the value of `GCM_TRACE_SECRETS` is `true` or `1`, trace logs will include +secret information. Defaults to disabled. @@ -70,8 +77,8 @@ _No configuration equivalent._ ### GCM_TRACE_MSAUTH -Enables inclusion of Microsoft Authentication libraries (ADAL, MSAL) logs in GCM trace output. -Requires that `GCM_TRACE` is also enabled. +Enables inclusion of Microsoft Authentication libraries (ADAL, MSAL) logs in GCM +trace output. Requires that `GCM_TRACE` is also enabled. #### Example @@ -89,7 +96,8 @@ export GCM_TRACE=$HOME/gcm.log export GCM_TRACE_MSAUTH=1 ``` -If the value of `GCM_TRACE_MSAUTH` is `true` or `1`, trace logs will include verbose ADAL/MSAL logs. +If the value of `GCM_TRACE_MSAUTH` is `true` or `1`, trace logs will include +verbose ADAL/MSAL logs. Defaults to disabled. @@ -123,16 +131,21 @@ _No configuration equivalent._ ### GCM_INTERACTIVE -Permit or disable GCM from interacting with the user (showing GUI or TTY prompts). If interaction is required but has been disabled, an error is returned. +Permit or disable GCM from interacting with the user (showing GUI or TTY +prompts). If interaction is required but has been disabled, an error is +returned. -This can be helpful when using GCM in headless and unattended environments, such as build servers, where it would be preferable to fail than to hang indefinitely waiting for a non-existent user. +This can be helpful when using GCM in headless and unattended environments, such +as build servers, where it would be preferable to fail than to hang indefinitely +waiting for a non-existent user. To disable interactivity set this to `false` or `0`. #### Compatibility -In previous versions of GCM this setting had a different behavior and accepted other values. -The following table summarizes the change in behavior and the mapping of older values such as `never`: +In previous versions of GCM this setting had a different behavior and accepted +other values. The following table summarizes the change in behavior and the +mapping of older values such as `never`: Value(s)|Old meaning|New meaning -|-|- @@ -174,7 +187,9 @@ ID|Provider Automatic provider selection is based on the remote URL. -This setting is typically used with a scoped URL to map a particular set of remote URLs to providers, for example to mark a host as a GitHub Enterprise instance. +This setting is typically used with a scoped URL to map a particular set of +remote URLs to providers, for example to mark a host as a GitHub Enterprise +instance. #### Example @@ -196,11 +211,13 @@ export GCM_PROVIDER=github ### GCM_AUTHORITY _(deprecated)_ -> This setting is deprecated and should be replaced by `GCM_PROVIDER` with the corresponding provider ID value. +> This setting is deprecated and should be replaced by `GCM_PROVIDER` with the +> corresponding provider ID value. > > 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. +Select the host provider to use when authenticating by which authority is +supported by the providers. Authority|Provider(s) -|- @@ -286,7 +303,9 @@ export GCM_AUTODETECT_TIMEOUT=-1 ### GCM_ALLOW_WINDOWSAUTH -Allow detection of Windows Integrated Authentication (WIA) support for generic host providers. Setting this value to `false` will prevent the use of WIA and force a basic authentication prompt when using the Generic host provider. +Allow detection of Windows Integrated Authentication (WIA) support for generic +host providers. Setting this value to `false` will prevent the use of WIA and +force a basic authentication prompt when using the Generic host provider. **Note:** WIA is only supported on Windows. @@ -317,7 +336,8 @@ export GCM_ALLOW_WINDOWSAUTH=0 ### GCM_HTTP_PROXY _(deprecated)_ -> This setting is deprecated and should be replaced by the [standard `http.proxy` Git configuration option][git-httpproxy]. +> This setting is deprecated and should be replaced by the [standard `http.proxy` +> Git configuration option][git-httpproxy]. > > See the [HTTP proxy configuration][network-http-proxy] for more information. @@ -343,10 +363,12 @@ export GCM_HTTP_PROXY=http://john.doe:password@proxy.contoso.com ### GCM_BITBUCKET_AUTHMODES -Override the available authentication modes presented during Bitbucket authentication. -If this option is not set, then the available authentication modes will be automatically detected. +Override the available authentication modes presented during Bitbucket +authentication. If this option is not set, then the available authentication +modes will be automatically detected. -**Note:** This setting only applies to Bitbucket.org, and not Server or DC instances. +**Note:** This setting only applies to Bitbucket.org, and not Server or DC +instances. **Note:** This setting supports multiple values separated by commas. @@ -374,13 +396,20 @@ export GCM_BITBUCKET_AUTHMODES="oauth,basic" ### GCM_BITBUCKET_ALWAYS_REFRESH_CREDENTIALS -Forces GCM to ignore any existing stored Basic Auth or OAuth access tokens and always run through the process to refresh the credentials before returning them to Git. +Forces GCM to ignore any existing stored Basic Auth or OAuth access tokens and +always run through the process to refresh the credentials before returning them +to Git. -This is especially relevant to OAuth credentials. Bitbucket.org access tokens expire after 2 hours, after that the refresh token must be used to get a new access token. +This is especially relevant to OAuth credentials. Bitbucket.org access tokens +expire after 2 hours, after that the refresh token must be used to get a new +access token. -Enabling this option will improve performance when using Oauth2 and interacting with Bitbucket.org if, on average, commits are done less frequently than every 2 hours. +Enabling this option will improve performance when using Oauth2 and interacting +with Bitbucket.org if, on average, commits are done less frequently than every 2 +hours. -Enabling this option will decrease performance when using Basic Auth by requiring the user the re-enter credentials every time. +Enabling this option will decrease performance when using Basic Auth by +requiring the user the re-enter credentials every time. Value|Refresh Credentials Before Returning -|- @@ -407,8 +436,9 @@ Defaults to false/disabled. ### GCM_GITHUB_AUTHMODES -Override the available authentication modes presented during GitHub authentication. -If this option is not set, then the available authentication modes will be automatically detected. +Override the available authentication modes presented during GitHub +authentication. If this option is not set, then the available authentication +modes will be automatically detected. **Note:** This setting supports multiple values separated by commas. @@ -439,8 +469,9 @@ export GCM_GITHUB_AUTHMODES="oauth,basic" ### GCM_GITLAB_AUTHMODES -Override the available authentication modes presented during GitLab authentication. -If this option is not set, then the available authentication modes will be automatically detected. +Override the available authentication modes presented during GitLab +authentication. If this option is not set, then the available authentication +modes will be automatically detected. **Note:** This setting supports multiple values separated by commas. @@ -469,8 +500,8 @@ export GCM_GITLAB_AUTHMODES="browser" ### GCM_NAMESPACE -Use a custom namespace prefix for credentials read and written in the OS credential store. -Credentials will be stored in the format `{namespace}:{service}`. +Use a custom namespace prefix for credentials read and written in the OS +credential store. Credentials will be stored in the format `{namespace}:{service}`. Defaults to the value `git`. @@ -494,9 +525,11 @@ export GCM_NAMESPACE="my-namespace" 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. +Default value on Windows is `wincredman`, on macOS is `keychain`, and is unset +on Linux. -**Note:** For more information about configuring secret stores see the [credential stores documentation][credential-stores]. +**Note:** For more information about configuring secret stores see the +[credential stores documentation][credential-stores]. Value|Credential Store|Platforms -|-|- @@ -554,7 +587,8 @@ export GCM_CREDENTIAL_CACHE_OPTIONS="--timeout 300" ### 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`. @@ -576,7 +610,8 @@ export GCM_PLAINTEXT_STORE_PATH=/mnt/external-drive/credentials ### 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`. @@ -592,9 +627,13 @@ SETX GCM_DPAPI_STORE_PATH=D:\credentials ### GCM_GPG_PATH -Specify the path (_including_ the executable name) to the version of `gpg` used by `pass` (`gpg2` if present, otherwise `gpg`). This is primarily meant to allow manual resolution of the conflict that occurs on legacy Linux systems with parallel installs of `gpg` and `gpg2`. +Specify the path (_including_ the executable name) to the version of `gpg` used +by `pass` (`gpg2` if present, otherwise `gpg`). This is primarily meant to allow +manual resolution of the conflict that occurs on legacy Linux systems with +parallel installs of `gpg` and `gpg2`. -If not specified, GCM defaults to using the version of `gpg2` on the `$PATH`, falling back on `gpg` if `gpg2` is not found. +If not specified, GCM defaults to using the version of `gpg2` on the `$PATH`, +falling back on `gpg` if `gpg2` is not found. #### macOS/Linux @@ -608,7 +647,8 @@ _No configuration equivalent._ ### GCM_MSAUTH_FLOW -Specify which authentication flow should be used when performing Microsoft authentication and an interactive flow is required. +Specify which authentication flow should be used when performing Microsoft +authentication and an interactive flow is required. Defaults to `auto`. @@ -646,7 +686,9 @@ 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] 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 -|- diff --git a/docs/faq.md b/docs/faq.md index a6067dfb3..7008b793b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -6,48 +6,74 @@ Please follow these steps to diagnose or resolve the problem: -1. Check if you can access the remote repository in a web browser. If you cannot, this is probably a permission problem and you should follow up with the repository administrator for access. Execute `git remote -v` from a terminal to show the remote URL. +1. Check if you can access the remote repository in a web browser. If you +cannot, this is probably a permission problem and you should follow up with the +repository administrator for access. Execute `git remote -v` from a terminal to +show the remote URL. -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. 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 in the [environment doc][env-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][create-issue], 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 -To keep your data secure, Git Credential Manager will not send credentials for Azure Repos, Azure DevOps Server (TFS), GitHub, and Bitbucket, over HTTP connections that are not secured using TLS (HTTPS). +To keep your data secure, Git Credential Manager will not send credentials for +Azure Repos, Azure DevOps Server (TFS), GitHub, and Bitbucket, over HTTP +connections that are not secured using TLS (HTTPS). 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 in the [network config doc][netconfig-http-proxy]. +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][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][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. +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. -Git Credential Manager (GCM; this project) aims to replace both GCM Windows and Java GCM with a unified codebase which should be easier to maintain and enhance in the future. +Git Credential Manager (GCM; this project) aims to replace both GCM Windows and +Java GCM with a unified codebase which should be easier to maintain and enhance +in the future. ### Q: Does this mean GCM for Windows (.NET Framework-based) is deprecated? -Yes. Git Credential Manager for Windows (GCM Windows) is no longer receiving updates and fixes. All development effort has now been directed to GCM. GCM is available as an credential helper option in Git for Windows 2.28, and will be made the default helper in 2.29. +Yes. Git Credential Manager for Windows (GCM Windows) is no longer receiving +updates and fixes. All development effort has now been directed to GCM. GCM is +available as an credential helper option in Git for Windows 2.28, and will be +made the default helper in 2.29. ### 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][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 -GCM is only useful for HTTP(S)-based remotes. Git supports SSH out-of-the box so you shouldn't need to install anything else. +GCM is only useful for HTTP(S)-based remotes. Git supports SSH out-of-the box so +you shouldn't need to install anything else. To use SSH please follow the below links: @@ -57,7 +83,8 @@ To use SSH please follow the below links: ### Q: Are HTTP(S) remotes preferred over SSH? -No, neither are "preferred". SSH isn't going away, and is supported "natively" in Git. +No, neither are "preferred". SSH isn't going away, and is supported "natively" +in Git. ### Q: Why did you not just port the existing GCM Windows codebase from .NET Framework to .NET Core? @@ -65,31 +92,53 @@ GCM Windows was not designed with a cross-platform architecture. ### What level of support does GCM have? -Support will be best-effort. We would really appreciate your feedback to make this a great experience across each platform we support. +Support will be best-effort. We would really appreciate your feedback to make +this a great experience across each platform we support. ### Q: Why does GCM not support operating system/distribution 'X', or Git hosting provider 'Y'? The likely answer is we haven't gotten around to that yet! 🙂 -We are working on ensuring support for the Windows, macOS, and Ubuntu operating system, as well as the following Git hosting providers: Azure Repos, Azure DevOps Server (TFS), GitHub, and Bitbucket. +We are working on ensuring support for the Windows, macOS, and Ubuntu operating +system, as well as the following Git hosting providers: Azure Repos, Azure +DevOps Server (TFS), GitHub, and Bitbucket. -We are happy to accept proposals and/or contributions to enable GCM to run on other platforms and Git host providers. Thank you! +We are happy to accept proposals and/or contributions to enable GCM to run on +other platforms and Git host providers. Thank you! ## Technical ### Why is the `credential.useHttpPath` setting required for `dev.azure.com`? -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, hence the need for the `credential.useHttpPath` setting with GCM. +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, 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] 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. +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. -If you know which provider you're talking to and want to avoid the probe, that's possible. You can explicitly tell GCM which provider to use for a URL "example.com" like this: +If you know which provider you're talking to and want to avoid the probe, that's +possible. You can explicitly tell GCM which provider to use for a URL +"example.com" like this: Provider|Command -|- @@ -100,15 +149,23 @@ 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][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. +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] 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] 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? @@ -117,7 +174,8 @@ customize how GCM will prompt you (or not) for input. Please see the following: - [`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) +- [`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? @@ -145,7 +203,9 @@ and pick "Revoke access". ![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. +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? @@ -153,17 +213,22 @@ 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: +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**][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). +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][gitlab-oauthapp-revoke] 4. Waiting for a notification stating **The application was revoked access**. ![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). +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 diff --git a/docs/gitlab.md b/docs/gitlab.md index 1b9687a6b..1abd272d8 100644 --- a/docs/gitlab.md +++ b/docs/gitlab.md @@ -4,14 +4,25 @@ 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: +To use on another instance, eg. `https://gitlab.example.com` requires setup and +configuration: -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` -1. For good measure, configure `git config --global credential.https://gitlab.example.com.provider gitlab`. This may be necessary to recognise the domain as a GitLab instance. -1. Verify the config is as expected `git config --global --get-urlmatch credential https://gitlab.example.com` +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` +1. For good measure, configure +`git config --global credential.https://gitlab.example.com.provider gitlab`. +This may be necessary to recognise the domain as a GitLab instance. +1. Verify the config is as expected +`git config --global --get-urlmatch credential https://gitlab.example.com` ### Clearing config @@ -31,7 +42,8 @@ Select an authentication method for 'https://gitlab.com/': option (enter for default): ``` -If you have a preferred authentication mode, you can specify [credential.gitLabAuthModes][config-gitlab-auth-modes]: +If you have a preferred authentication mode, you can specify +[credential.gitLabAuthModes][config-gitlab-auth-modes]: ```console git config --global credential.gitlabauthmodes browser @@ -39,11 +51,15 @@ git config --global credential.gitlabauthmodes browser ## Caveats -Improved support requires changes in GitLab. Please vote for these issues if they affect you: +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][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] +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 diff --git a/docs/linux-fromsrc-uninstall.md b/docs/linux-fromsrc-uninstall.md index 425312dea..e367c89bf 100644 --- a/docs/linux-fromsrc-uninstall.md +++ b/docs/linux-fromsrc-uninstall.md @@ -1,16 +1,28 @@ # Uninstalling after installing from source -These instructions will guide you in removing GCM after running the [install from source script][install-from-source] 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: -For completeness, we provide uninstall instructions for _the GCM application, the GCM repo, and the maximum number of dependencies*_ for all distributions. This repo and these dependencies may or may not have already been present on your system when you ran the install from source script, and uninstalling them could impact other programs and/or your normal workflows. Please keep this in mind when following the instructions below. +For completeness, we provide uninstall instructions for _the GCM application, +the GCM repo, and the maximum number of dependencies*_ for all distributions. +This repo and these dependencies may or may not have already been present on +your system when you ran the install from source script, and uninstalling them +could impact other programs and/or your normal workflows. Please keep this in +mind when following the instructions below. -*Certain distributions require some dependencies of the script to function as expected, so we only include instructions to remove the non-required dependencies. +*Certain distributions require some dependencies of the script to function as +expected, so we only include instructions to remove the non-required +dependencies. ## All distributions -**Note:** If you ran the install from source script from a pre-existing clone of the `git-credential-manager` repo or outside of your `$HOME` directory, you will need to modify the final two commands below to point to the location of your pre-existing clone or the directory from which you ran the install from source script. +**Note:** If you ran the install from source script from a pre-existing clone of +the `git-credential-manager` repo or outside of your `$HOME` directory, you will +need to modify the final two commands below to point to the location of your +pre-existing clone or the directory from which you ran the install from source +script. ```console git-credential-manager-core unconfigure && @@ -22,7 +34,10 @@ 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][uninstall-dotnet] 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 +45,11 @@ 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][uninstall-dotnet]. +**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 +58,11 @@ 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][uninstall-dotnet]. +**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,11 +70,16 @@ 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][uninstall-dotnet]. +**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 +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 diff --git a/docs/migration.md b/docs/migration.md index 88ba8da89..8ad6e392e 100644 --- a/docs/migration.md +++ b/docs/migration.md @@ -4,11 +4,17 @@ ### GCM_AUTHORITY -This setting (and the corresponding `credential.authority` configuration) is deprecated and should be replaced with the `GCM_PROVIDER` (or corresponding `credential.authority` configuration) setting. +This setting (and the corresponding `credential.authority` configuration) is +deprecated and should be replaced with the `GCM_PROVIDER` (or corresponding +`credential.authority` configuration) setting. -Because both Basic HTTP authentication and Windows Integrated Authentication (WIA) are now handled by one provider, if you specified `basic` as your authority you also need to disable WIA using `GCM_ALLOW_WINDOWSAUTH` / `credential.allowWindowsAuth`. +Because both Basic HTTP authentication and Windows Integrated Authentication +(WIA) are now handled by one provider, if you specified `basic` as your +authority you also need to disable WIA using `GCM_ALLOW_WINDOWSAUTH` / +`credential.allowWindowsAuth`. -The following table shows the correct replacement for all legacy authorities values: +The following table shows the correct replacement for all legacy authorities +values: GCM_AUTHORITY (credential.authority)|→|GCM_PROVIDER (credential.provider)|GCM_ALLOW_WINDOWSAUTH (credential.allowWindowsAuth) -|-|-|- @@ -17,7 +23,8 @@ GCM_AUTHORITY (credential.authority)|→|GCM_PROVIDER (credential.provider)|G `basic`|→|`generic`|`false` `integrated`, `windows`, `kerberos`, `ntlm`, `tfs`, `sso`|→|`generic`|`true` _(default)_ -For example if you had previous set the authority for the `example.com` host to `basic`.. +For example if you had previous set the authority for the `example.com` host to +`basic`.. ```shell git config --global credential.example.com.authority basic diff --git a/docs/multiple-users.md b/docs/multiple-users.md index 8fb3e0c71..b02b35a42 100644 --- a/docs/multiple-users.md +++ b/docs/multiple-users.md @@ -1,24 +1,47 @@ # Multiple users -If you work with multiple different identities on a single Git hosting service, you may be wondering if Git Credential Manager (GCM) supports this workflow. The answer is yes, with a bit of complexity due to how it interoperates with Git. +If you work with multiple different identities on a single Git hosting service, +you may be wondering if Git Credential Manager (GCM) supports this workflow. The +answer is yes, with a bit of complexity due to how it interoperates with Git. ## Foundations: Git and Git hosts -Git itself doesn't have a single, strong concept of "user". There's the `user.name` and `user.email` which get embedded into commit headers/trailers, but these are arbitrary strings. GCM doesn't interact with this notion of a user at all. You can put whatever you want into your `user.*` config, and nothing in GCM will change at all. +Git itself doesn't have a single, strong concept of "user". There's the +`user.name` and `user.email` which get embedded into commit headers/trailers, +but these are arbitrary strings. GCM doesn't interact with this notion of a user +at all. You can put whatever you want into your `user.*` config, and nothing in +GCM will change at all. -Separate from the user strings in commits, Git recognizes the "user" part of a remote URL or a credential. These are not often used, at least by default, in the web UI of major Git hosts. +Separate from the user strings in commits, Git recognizes the "user" part of a +remote URL or a credential. These are not often used, at least by default, in +the web UI of major Git hosts. -Git hosting providers (like GitHub or Bitbucket) _do_ have a concept of "user". Typically it's an identity like a username or email address, plus a password or other credential to perform actions as that user. You may have guessed by now that GCM (the Git **Credential** Manager) does work with this notion of a user. +Git hosting providers (like GitHub or Bitbucket) _do_ have a concept of "user". +Typically it's an identity like a username or email address, plus a password or +other credential to perform actions as that user. You may have guessed by now +that GCM (the Git **Credential** Manager) does work with this notion of a user. ## People, identities, credentials, oh my -You (a physical person) may have one or more user accounts (identities) with one or more Git hosting providers. Since most Git hosts don't put a "user" part in their URLs, by default, Git will treat the user part for a remote as the empty string. If you have multiple identities on one domain, you'll need to insert a unique user part per-identity yourself. - -There are good reasons for having multiple identities on one domain. You might use one GitHub identity for your personal work, another for your open source work, and a third for your employer's work. You can ask Git to assign a different credential to different repositories hosted on the same provider. HTTPS URLs include an optional "name" part before an `@` sign in the domain name, and you can use this to force Git to distinguish multiple users. This should likely be your username on the Git hosting service, since there are cases where GCM will use it like a username. +You (a physical person) may have one or more user accounts (identities) with one +or more Git hosting providers. Since most Git hosts don't put a "user" part in +their URLs, by default, Git will treat the user part for a remote as the empty +string. If you have multiple identities on one domain, you'll need to insert a +unique user part per-identity yourself. + +There are good reasons for having multiple identities on one domain. You might +use one GitHub identity for your personal work, another for your open source +work, and a third for your employer's work. You can ask Git to assign a +different credential to different repositories hosted on the same provider. +HTTPS URLs include an optional "name" part before an `@` sign in the domain +name, and you can use this to force Git to distinguish multiple users. This +should likely be your username on the Git hosting service, since there are +cases where GCM will use it like a username. ## Setting it up -As an example, let's say you're working on multiple repositories hosted at the same domain name. +As an example, let's say you're working on multiple repositories hosted at the +same domain name. | Repo URL | Identity | |----------|----------| @@ -26,7 +49,9 @@ As an example, let's say you're working on multiple repositories hosted at the s | `https://example.com/more-open-source/app.git` | `contrib123` | | `https://example.com/big-company/secret-repo.git` | `employee9999` | -When you clone these repos, include the identity and an `@` before the domain name in order to force Git and GCM to use different identities. If you've already cloned the repos, you can update the remote URL to include the identity. +When you clone these repos, include the identity and an `@` before the domain +name in order to force Git and GCM to use different identities. If you've +already cloned the repos, you can update the remote URL to include the identity. ### Example: fresh clones @@ -50,6 +75,7 @@ git remote set-url origin https://employee9999@example.com/big-company/secret-re ## Azure DevOps -[Azure DevOps has some additional, optional complexity][azure-access-tokens] 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 8d9c4bfa8..aef5b0753 100644 --- a/docs/netconfig.md +++ b/docs/netconfig.md @@ -1,12 +1,17 @@ # 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] and [configuration options][configuration]. +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. +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`][git-http-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`][git-http-proxy]. For example to configure a proxy for all remotes for the current user: @@ -14,31 +19,43 @@ 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][git-remote-name-proxy], 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 ``` -The advantage to using these standard configuration options is that in addition to GCM being configured to use the proxy, Git itself will be configured at the same time. This is probably the most commonly desired case in environments behind an Internet-blocking firewall. +The advantage to using these standard configuration options is that in addition +to GCM being configured to use the proxy, Git itself will be configured at the +same time. This is probably the most commonly desired case in environments +behind an Internet-blocking firewall. ### Authenticated proxies -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. +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][rfc-3986-321] 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 ``` -For example, to specify the username `john.doe` and the password `letmein123` for the proxy server `proxy.example.com`: +For example, to specify the username `john.doe` and the password `letmein123` +for the proxy server `proxy.example.com`: ```text https://john.doe:letmein123@proxy.example.com ``` -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]). +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`. @@ -53,7 +70,8 @@ GCM supports other ways of configuring a proxy for convenience and compatibility - `http_proxy` - `https_proxy`/`HTTPS_PROXY` - `all_proxy`/`ALL_PROXY` -1. `GCM_HTTP_PROXY` environment variable (_**only** respected by GCM; **deprecated**_) +1. `GCM_HTTP_PROXY` environment variable (_**only** respected by GCM; +**deprecated**_) Note that with the cURL environment variables there are both lowercase and uppercase variants. @@ -106,29 +124,45 @@ no_proxy="contoso.com,www.fabrikam.com" ## TLS Verification -If you are using self-signed TLS (SSL) certificates with a self-hosted host provider such as GitHub Enterprise Server or Azure DevOps Server (previously TFS), you may see the following error message when attempting to connect using Git and/or GCM: +If you are using self-signed TLS (SSL) certificates with a self-hosted host +provider such as GitHub Enterprise Server or Azure DevOps Server (previously +TFS), you may see the following error message when attempting to connect using +Git and/or GCM: ```shell $ 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][lets-encrypt], [Comodo][comodo], [Digicert][digicert], [GoDaddy][godaddy], [GlobalSign][globalsign]. +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][mac-keychain-access], [Windows][install-cert-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. +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][mitm-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). +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`][git-ssl-no-verify] and [Git configuration option `http.sslVerify`][git-http-ssl-verify] 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 `https://example.com`): @@ -136,7 +170,8 @@ To disable verification for a specific remote (for example `https://example.com` git config --global http.https://example.com.sslVerify false ``` -To disable verification for the current user for **_all remotes_** (**not recommended**): +To disable verification for the current user for **_all remotes_** (**not +recommended**): ```shell # Environment variable (Windows) @@ -151,7 +186,10 @@ 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][telerik-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 diff --git a/docs/usage.md b/docs/usage.md index 1a3b1e89b..4398ff030 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -1,9 +1,12 @@ # Command-line usage -After installation, Git will use Git Credential Manager and you will only need to interact with any authentication dialogs asking for credentials. -GCM stays invisible as much as possible, so ideally you’ll forget that you’re depending on GCM at all. +After installation, Git will use Git Credential Manager and you will only need +to interact with any authentication dialogs asking for credentials. +GCM stays invisible as much as possible, so ideally you’ll forget that you’re +depending on GCM at all. -Assuming GCM has been installed, use your favorite terminal to execute the following commands to interact directly with GCM. +Assuming GCM has been installed, use your favorite terminal to execute the +following commands to interact directly with GCM. ```shell git credential-manager-core [ []] @@ -23,7 +26,8 @@ Displays the current version. Commands for interaction with Git. You shouldn't need to run these manually. -Read the [Git manual][git-credentials-custom-helpers] about custom helpers for more information. +Read the [Git manual][git-credentials-custom-helpers] about custom helpers for +more information. ### configure/unconfigure @@ -33,10 +37,12 @@ Set your user-level Git configuration (`~/.gitconfig`) to use GCM. If you pass ### azure-repos -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. +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][azure-access-tokens-ua]. +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 79190ea72..c767c172d 100644 --- a/docs/windows-broker.md +++ b/docs/windows-broker.md @@ -1,41 +1,58 @@ # Web Account Manager integration -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][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. +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][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][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`][GCM_MSAUTH_USEBROKER] or setting the Git configuration value [`credential.msauthUseBroker`][credential.msauthUseBroker]. +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 -When you turn on WAM support, GCM can cooperate with Windows and with other WAM-enabled software on your machine. -This means a more seamless experience, fewer multi-factor authentication prompts, and the ability to use additional authentication technologies like smart cards and Windows Hello. -These convenience and security features make a good case for enabling WAM. +When you turn on WAM support, GCM can cooperate with Windows and with other +WAM-enabled software on your machine. This means a more seamless experience, +fewer multi-factor authentication prompts, and the ability to use additional +authentication technologies like smart cards and Windows Hello. These +convenience and security features make a good case for enabling WAM. ## Surprising behaviors -The WAM and Windows identity systems are complex, addressing a very broad range of customer use cases. -What works for a solo home user may not be adequate for a corporate-managed fleet of 100,000 devices and vice versa. -The GCM team isn't responsible for the user experience or choices made by WAM, but by integrating with WAM, we inherit some of those choices. -Therefore, we want you to be aware of some defaults and experiences if you choose to use WAM integration. +The WAM and Windows identity systems are complex, addressing a very broad range +of customer use cases. What works for a solo home user may not be adequate for a +corporate-managed fleet of 100,000 devices and vice versa. The GCM team isn't +responsible for the user experience or choices made by WAM, but by integrating +with WAM, we inherit some of those choices. Therefore, we want you to be aware +of some defaults and experiences if you choose to use WAM integration. ### For work or school accounts (Azure AD-backed identities) -When you sign into an Azure DevOps organization backed by Azure AD (often your company or school email), if your machine is already joined to Azure AD matching that Azure DevOps organization, you'll get a seamless and easy-to-use experience. +When you sign into an Azure DevOps organization backed by Azure AD (often your +company or school email), if your machine is already joined to Azure AD matching +that Azure DevOps organization, you'll get a seamless and easy-to-use experience. -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: +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][aad-questions] @@ -43,24 +60,40 @@ The dialog box has changed a bit in various versions of Windows; here are two ex 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. +- 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][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. +- 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. -Despite joining Azure AD, your organization's Conditional Access policies may still prevent you from accessing Azure DevOps. +Other apps may log you in automatically or prompt you again to allow your +organization to manage your device. Despite joining Azure AD, your +organization's Conditional Access policies may still prevent you from accessing +Azure DevOps. 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 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][GCM_MSAUTH_USEBROKER] (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**. +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][aad-work-school] @@ -68,16 +101,23 @@ In the section where you see your email address and organization name, click **D ### For Microsoft accounts -When you sign into an Azure DevOps organization backed by Microsoft account (MSA) identities (email addresses like `@outlook.com` or `@gmail.com` fall into this category), you may be prompted to select an existing "work or school account" or use a different one. +When you sign into an Azure DevOps organization backed by Microsoft account +(MSA) identities (email addresses like `@outlook.com` or `@gmail.com` fall into +this category), you may be prompted to select an existing "work or school +account" or use a different one. -In order to sign in with an MSA you should continue and select "Use a different [work or school] account", but enter your MSA credentials when prompted. -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. +In order to sign in with an MSA you should continue and select "Use a different +[work or school] account", but enter your MSA credentials when prompted. 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][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**: +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][all-ms-apps] @@ -85,24 +125,34 @@ For any connected MSA, you can control whether or not the account is available t Two very important things to note: -- If you haven't connected any Microsoft accounts to Windows before, the first account you connect will cause the local Windows user account to be converted to a connected account. -- In addition, you can't change the usage preference for the first Microsoft account connected to Windows: all Microsoft apps will be able to sign you in with that account. +- If you haven't connected any Microsoft accounts to Windows before, the first +account you connect will cause the local Windows user account to be converted to +a connected account. +- In addition, you can't change the usage preference for the first Microsoft +account connected to Windows: all Microsoft apps will be able to sign you in +with that account. -As far as we can tell, there are no workarounds for either of these behaviors (other than to not use the WAM broker). +As far as we can tell, there are no workarounds for either of these behaviors +(other than to not use the WAM broker). ## Running as administrator -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. +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. If you've enabled using the broker, GCM will check whether it's running in an -elevated process. -If it is, GCM will automatically attempt to modify the COM security settings for the running process so that GCM and WAM can work together. +elevated process. If it is, GCM will automatically attempt to modify the COM +security settings for the running process so that GCM and WAM can work together. However, this automatic process security change is not guaranteed to succeed. -Various external factors like registry or system-wide COM settings may cause it to fail. -If GCM can't modify the process's COM security settings, GCM prints a warning message and won't be able to use the broker. +Various external factors like registry or system-wide COM settings may cause it +to fail. If GCM can't modify the process's COM security settings, GCM prints a +warning message and won't be able to use the broker. ```text warning: broker initialization failed diff --git a/docs/wsl.md b/docs/wsl.md index d9e298ee5..bae6bdb53 100644 --- a/docs/wsl.md +++ b/docs/wsl.md @@ -64,7 +64,8 @@ After updating the `WSLENV` environment variable, restart your WSL installation. If you have installed GCM using the user-only installer (i.e, the `gcmuser-*.exe` installer and not the system-wide/admin required installer), you need to modify -the above instructions to point to `/mnt/c/Users//AppData/Local/Programs/Git\ Credential\ Manager\ Core/git-credential-manager-core.exe` +the above instructions to point to +`/mnt/c/Users//AppData/Local/Programs/Git\ Credential\ Manager\ Core/git-credential-manager-core.exe` instead. ## How it works @@ -102,7 +103,8 @@ 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][linux-installation]. +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