Git Credential Manager (GCM) Core knows how to integrate with the Web Account Manager (WAM) 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, 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. It doesn't impact authentication with GitHub, Bitbucket, or any other Git host.
You can opt-in to WAM support by setting the environment variable GCM_MSAUTH_USEBROKER or setting the Git configuration value credential.msauthUseBroker.
When you turn on WAM support, GCM Core 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.
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 Core 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.
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:
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 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. If so, you'll be prompted with instructions on how to enroll in MDM.
- If you instead click "No, sign in to this app only", your machine will not be joined to Azure AD or MDM-enrolled, so no policies can be enforced, and your identity won't be made available to other apps on the computer. Similar to the above, your organization's Conditional Access policies may prevent you from proceeding.
If Conditional Access is required to access your organization's Git repositories, you can enable WAM integration (or follow other instructions your organization provides).
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.
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.
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:
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.
As far as we can tell, there are no workarounds for either of these behaviors (other than to not use the WAM broker).
The Windows broker ("WAM") makes heavy use of 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) 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. 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.
warning: broker initialization failed
Failed to set COM process security to allow Windows broker from an elevated process (0x80010119).
See https://aka.ms/gcmcore-wamadmin for more information.
In order to fix the problem, there are a few options:
- Run Git or Git Credential Manager from non-elevated processes.
- Disable the broker by setting the
GCM_MSAUTH_USEBROKERenvironment variable or thecredential.msauthUseBrokerGit configuration setting tofalse.