docs: add bitbucket app password requirements

Separate Bitbucket Authentication information for users from development
information for developers. Use this opportunity to also add the
permissions requirements for users attempting to authenticate to Bitbucket
with an App Password.

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 the 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: