introduce new windows-broker doc

DitZii · May 14, 2021 · 41feccd · 41feccd
1 parent 301f888
commit 41feccd
Show file tree

Hide file tree

Showing 10 changed files with 75 additions and 2 deletions.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -280,12 +280,14 @@ git config --global credential.msauthFlow devicecode
 
 ---
 
-### credential.msauthUseBroker
+### credential.msauthUseBroker _(experimental)_
 
 Use the operating system account manager where available.
 
 Defaults to `false`. This default is subject to change in the future.
 
+_**Note:** before you enable this option on Windows, please [review the details](windows-broker.md) about what this means to your local Windows user account._
+
 Value|Description
 -|-
 `true`|Use the operating system account manager as an authentication broker.

diff --git a/docs/environment.md b/docs/environment.md
@@ -432,12 +432,14 @@ export GCM_MSAUTH_FLOW="devicecode"
 
 ---
 
-### GCM_MSAUTH_USEBROKER
+### GCM_MSAUTH_USEBROKER _(experimental)_
 
 Use the operating system account manager where available.
 
 Defaults to `false`. This default is subject to change in the future.
 
+_**Note:** before you enable this option on Windows, please [review the details](windows-broker.md) about what this means to your local Windows user account._
+
 Value|Description
 -|-
 `true`|Use the operating system account manager as an authentication broker.

diff --git a/docs/img/aad-bitlocker.png b/docs/img/aad-bitlocker.png
diff --git a/docs/img/aad-disconnect.png b/docs/img/aad-disconnect.png
diff --git a/docs/img/aad-questions.png b/docs/img/aad-questions.png
diff --git a/docs/img/aad-work-school.png b/docs/img/aad-work-school.png
diff --git a/docs/img/all-microsoft.png b/docs/img/all-microsoft.png
diff --git a/docs/img/apps-must-ask.png b/docs/img/apps-must-ask.png
diff --git a/docs/img/get-signed-in.png b/docs/img/get-signed-in.png
diff --git a/docs/windows-broker.md b/docs/windows-broker.md
@@ -0,0 +1,69 @@
+# Web Account Manager integration
+
+Git Credential Manager (GCM) Core knows how to integrate with the [Web Account Manager (WAM)](https://docs.microsoft.com/azure/active-directory/devices/concept-primary-refresh-token#key-terminology-and-components) feature of Windows 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.
+Integration with the WAM broker comes with several additional benefits, but it also has some potential drawbacks that you should be aware of before enabling it.
+
+Note that this only affects Azure DevOps.
+It doesn't impact authentication with GitHub, Bitbucket, or any other Git host.
+
+## Features
+
+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.
+
+## Potential drawbacks
+
+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.
+
+### For work or school accounts (Azure AD-backend identities)
+When you sign into an Azure DevOps organization backed by Azure AD (often your company or school email), if your machine is already managed by Intune or enrolled in Azure AD matching that Azure DevOps organization, you'll get a seamless and easy-to-use experience.
+
+If your machine isn't Intune/Azure AD-joined, or is Intune/Azure AD-joined to a different tenant, WAM will present you with the following dialog box:
+
+![Consent dialog](img/aad-questions.png)
+
+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 Intune-enrolled, meaning an administrator can deploy policies to your machine: requiring certain kinds of sign-in, turning on antivirus and firewall software, and enabling BitLocker.
+Your identity will also be available to other apps on the computer for signing in, some of which may do so automatically.
+![Example of policies pushed to an Intune-enrolled device](img/aad-bitlocker.png)
+- If you uncheck "allow my organization to manage my device" and click "OK", your computer won't be registered with Azure AD or Intune-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.
+- If you instead click "No, sign in to this app only", your machine will not be Intune-enrolled, so no policies can be enforced, and your identity won't be made available to other apps on the computer.
+
+#### Removing device management
+If you've allowed your computer to be managed and want to undo it, you can go into **Settings**, **Accounts**, **Access work or school**.
+In the section where you see your email address and organization name, click **Disconnect**.
+
+![Finding your work or school account](img/aad-work-school.png)
+
+![Disconnecting from Azure AD](img/aad-disconnect.png)
+
+### 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.
+
+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](img/get-signed-in.png)
+
+If you've connected your MSA to Windows or signed-in to other Microsoft applications such as Office, then you may see this account listed in the authentication prompts when using GCM.
+For any connected MSA, you can control whether or not the account is available to other Microsoft applications in **Settings**, **Accounts**, **Emails & accounts**:
+
+![Allow all Microsoft apps to access your identity](img/all-microsoft.png)
+![Microsoft apps must ask to access your identity](img/apps-must-ask.png)
+
+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).