From 2c8cbebd8565bb188300655b7145dd854e5a4041 Mon Sep 17 00:00:00 2001
From: Frank Prins <25006490+PrinsFrank@users.noreply.github.com>
Date: Tue, 13 Oct 2020 23:30:47 +0200
Subject: [PATCH] Update authentication methods in documentation

---
 doc/03-cli.md                                 |  7 +-
 doc/06-config.md                              |  6 +-
 .../authentication-for-private-packages.md    | 64 +++++++++++++++++++
 doc/articles/troubleshooting.md               |  7 +-
 4 files changed, 72 insertions(+), 12 deletions(-)

diff --git a/doc/03-cli.md b/doc/03-cli.md
index 009dfd947..98bb9890a 100644
--- a/doc/03-cli.md
+++ b/doc/03-cli.md
@@ -900,9 +900,10 @@ If set to 1, this env allows running Composer when the Xdebug extension is enabl
 ### COMPOSER_AUTH
 
 The `COMPOSER_AUTH` var allows you to set up authentication as an environment variable.
-The contents of the variable should be a JSON formatted object containing http-basic,
-github-oauth, bitbucket-oauth, ... objects as needed, and following the
-[spec from the config](06-config.md#gitlab-oauth).
+The contents of the variable should be a JSON formatted object containing [http-basic,
+github-oauth, bitbucket-oauth, ... objects as needed](articles/authentication-for-private-packages.md),
+and following the
+[spec from the config](06-config.md).
 
 ### COMPOSER_BIN_DIR
 
diff --git a/doc/06-config.md b/doc/06-config.md
index dff151a77..fbdb9e364 100644
--- a/doc/06-config.md
+++ b/doc/06-config.md
@@ -71,9 +71,9 @@ URL.
 A list of domain names and oauth keys. For example using `{"github.com":
 "oauthtoken"}` as the value of this option will use `oauthtoken` to access
 private repositories on github and to circumvent the low IP-based rate limiting
-of their API. [Read
-more](articles/troubleshooting.md#api-rate-limit-and-oauth-tokens) on how to get
-an OAuth token for GitHub.
+of their API. Composer may prompt for credentials when needed, but these can also be
+manually set. Read more on how to get an OAuth token for GitHub and cli syntax
+[here](articles/authentication-for-private-packages.md#github-oauth).
 
 ## gitlab-oauth
 
diff --git a/doc/articles/authentication-for-private-packages.md b/doc/articles/authentication-for-private-packages.md
index 8e51ab7de..84107242e 100644
--- a/doc/articles/authentication-for-private-packages.md
+++ b/doc/articles/authentication-for-private-packages.md
@@ -22,6 +22,8 @@ for credentials and save them (or a token if Composer is able to retrieve one).
 |[Custom header](#custom-token-authentication)|no|
 |[gitlab-oauth](#gitlab-oauth)|yes|
 |[gitlab-token](#gitlab-token)|yes|
+|[github-oauth](#github-oauth)|yes|
+|[bitbucket-oauth](#bitbucket-oauth)|yes|
 
 Sometimes automatic authentication is not possible, or you may want to predefine
 authentication credentials.
@@ -93,6 +95,16 @@ You can open this file in your favorite editor and fix the error.
 It is also possible to add credentials to a `composer.json` on a per-project basis in the `config`
 section or directly in the repository definition.
 
+## Authentication using the COMPOSER_AUTH environment variable
+
+> **Note:** Using this method also has security implications.
+> Credentials passed using command line environment variables will most likely be stored in memory,
+> and on be persisted to a file like ```~/.bash_history```(linux) or ```ConsoleHost_history.txt```
+> (Powershell on Windows) when closing a session.
+
+The final option to supply Composer with credentials is to use the ```COMPOSER_AUTH``` environment variable.
+Read more about the usage of this environment variable [here](../03-cli.md#COMPOSER_AUTH).
+
 # Authentication methods
 
 ## http-basic
@@ -224,3 +236,55 @@ composer config [--global] --editor --auth
     }
 }
 ```
+
+## github-oauth
+
+To create a new access token, head to your [token settings section on Github](https://github.com/settings/tokens) and [generate a new token](https://github.com/settings/tokens/new). For public repositories when rate limited, the ```public_repo``` scope is required, for private repositories the ```repo:status``` scope is needed.
+Read more about it [here](https://github.com/blog/1509-personal-api-tokens).
+
+### Command line github-oauth
+
+```sh
+composer config [--global] github-oauth.github.com token
+```
+
+### Manual github-oauth
+
+```sh
+composer config [--global] --editor --auth
+```
+
+```json
+{
+    "github-oauth": {
+        "github.com": "token"
+    }
+}
+```
+
+## bitbucket-oauth
+
+Read more about how to set up oauth on bitbucket [here](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/).
+
+### Command line bitbucket-oauth
+
+```sh
+composer config [--global] bitbucket-oauth.bitbucket.org cosumer-key consumer-secret
+```
+
+### Manual bitbucket-oauth
+
+```sh
+composer config [--global] --editor --auth
+```
+
+```json
+{
+    "bitbucket-oauth": {
+        "bitbucket.org": {
+             "consumer-key": "key",
+             "consumer-secret": "secret"
+        }
+    }
+}
+```
diff --git a/doc/articles/troubleshooting.md b/doc/articles/troubleshooting.md
index 33471cd53..3c9045f0a 100644
--- a/doc/articles/troubleshooting.md
+++ b/doc/articles/troubleshooting.md
@@ -177,12 +177,7 @@ Because of GitHub's rate limits on their API it can happen that Composer prompts
 for authentication asking your username and password so it can go ahead with its work.
 
 If you would prefer not to provide your GitHub credentials to Composer you can
-manually create a token using the following procedure:
-
-1. [Create](https://github.com/settings/tokens) an OAuth token on GitHub.
-[Read more](https://github.com/blog/1509-personal-api-tokens) on this.
-
-2. Add it to the configuration running `composer config -g github-oauth.github.com <oauthtoken>`
+manually create a token using the [procedure documented here](authentication-for-private-packages.md#github-oauth).
 
 Now Composer should install/update without asking for authentication.