docs: add bitbucket app password requirements (#1213)

Separate instructions for authentication into a new
`bitbucket-authentication` file. For Password/Token authentication, add
a callout that, when using an App Password, account read permissions are
required.

Closes #1119

Author: ldennington

docs/bitbucket-authentication.md

@@ -0,0 +1,61 @@
+# Bitbucket Authentication
+
+When GCM is triggered by Git, it will check the `host` parameter passed
+to it. If this parameter contains `bitbucket.org` it will trigger Bitbucket
+authentication and prompt you for credentials. In this scenario, you have two
+options for authentication: `OAuth` or `Password/Token`.
+
+### OAuth
+
+The dialog GCM presents for authentication contains two tabs. The first tab
+(labeled `Browser`) will trigger OAuth Authentication. Clicking the `Sign in
+with your browser` button opens 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 triggers a flow on Bitbucket requiring you to log in
+(and potentially complete 2FA) to authorize GCM to access Bitbucket with the
+specified scopes. GCM will then spawn a temporary local webserver, listening on
+port 34106, to handle the OAuth redirect/callback. Assuming you successfully
+log into Bitbucket and authorize GCM, this callback will include the appropriate
+tokens for GCM to handle authencation. These tokens are then stored in your
+configured [credential store][credstores] and are returned to Git.
+
+### Password/Token
+
+**Note:** Bitbucket Data Center, also known as Bitbucket Server or Bitbucket On
+Premises, only supports Basic Authentication - please follow the below
+instructions if you are using this product.
+
+The dialog GCM presents for authentication contains two tabs. The second tab
+(labeled `Password/Token`) will trigger Basic Authentication. This tab contains
+two fields, one for your username and one for your password or token. If the
+`username` parameter was passed into GCM, that will pre-populate the username
+field, although it can be overridden. Enter your username (if needed) and your
+password or token (i.e. Bitbucket App Password) and click `Sign in`.
+
+:rotating_light: Requirements for App Passwords :rotating_light:
+
+If you are planning to use an [App Password][app-password] for basic
+authentication, it must at a minimum have _Account Read_ permissions (as shown
+below). If your App Password does not have these permissions, you will be
+re-prompted for credentials on every interaction with the server.
+
+![][app-password-example]
+
+When your username and password are submitted, GCM will attempt to retrieve a
+basic authentication token for these credentials via the Bitbucket REST API. If
+this is successful, the credentials, username, and password/token are stored in
+your configured [credential store][credstores] and are returned to Git.
+
+If the API request fails with a 401 return code, the entered username/password
+combination is invalid; nothing is stored and nothing is returned to Git. In
+this scenario, re-attempt authentication, ensuring your credentials are correct.
+
+If the API request fails with a 403 (Forbidden) return code, the username and
+password are valid, but 2FA is enabled on the corresponding Bitbucket Account.
+In this scenario, you will be prompted to complete the OAuth authentication
+process.  If this is successful, the credentials, username, and password/token
+are stored in your configured [credential store][credstores] and are returned to
+Git.
+
+[app-password]: https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/
+[app-password-example]: img/app-password.png
+[credstores]: ./credstores.md

docs/bitbucket-development.md

@@ -54,60 +54,12 @@ i.e. using a key such as `git:https://[email protected]/` rather than
 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.
-
-### 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.
-
-### 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.
-
-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].
 
-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: