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 1/3] 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 ` +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. From 53b09302876d9655b13a13e3cc2634f9100554b9 Mon Sep 17 00:00:00 2001 From: Frank Prins <25006490+PrinsFrank@users.noreply.github.com> Date: Tue, 13 Oct 2020 23:55:17 +0200 Subject: [PATCH 2/3] Move some duplicate documentation, link across multiple pages and clarify some texts --- doc/05-repositories.md | 19 +++------------ doc/06-config.md | 12 ++++------ .../authentication-for-private-packages.md | 24 ++++++++++++------- 3 files changed, 23 insertions(+), 32 deletions(-) diff --git a/doc/05-repositories.md b/doc/05-repositories.md index 64ec0325b..8ce30895d 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -316,23 +316,10 @@ Please note: #### BitBucket Driver Configuration -The BitBucket driver uses OAuth to access your private repositories via the BitBucket REST APIs, and you will need to create an OAuth consumer to use the driver, please refer to [Atlassian's Documentation](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html). You will need to fill the callback url with something to satisfy BitBucket, but the address does not need to go anywhere and is not used by Composer. +> **Note that the repository endpoint for BitBucket needs to be https rather than git.** -After creating an OAuth consumer in the BitBucket control panel, you need to setup your auth.json file with -the credentials like this (more info [here](https://getcomposer.org/doc/06-config.md#bitbucket-oauth)): -```json -{ - "bitbucket-oauth": { - "bitbucket.org": { - "consumer-key": "myKey", - "consumer-secret": "mySecret" - } - } -} -``` -**Note that the repository endpoint needs to be https rather than git.** - -Alternatively if you prefer not to have your OAuth credentials on your filesystem you may export the ```bitbucket-oauth``` block above to the [COMPOSER_AUTH](https://getcomposer.org/doc/03-cli.md#composer-auth) environment variable instead. +After setting up your bitbucket repository, you will also need to set up authentication. +Documentation for that [has moved here](articles/authentication-for-private-packages.md#bitbucket-oauth) #### Subversion Options diff --git a/doc/06-config.md b/doc/06-config.md index fbdb9e364..00c7a5d57 100644 --- a/doc/06-config.md +++ b/doc/06-config.md @@ -82,6 +82,7 @@ A list of domain names and oauth keys. For example using `{"gitlab.com": private repositories on gitlab. Please note: If the package is not hosted at gitlab.com the domain names must be also specified with the [`gitlab-domains`](06-config.md#gitlab-domains) option. +Further info can also be found [here](articles/authentication-for-private-packages.md#gitlab-oauth) ## gitlab-token @@ -95,6 +96,7 @@ Please note: If the package is not hosted at gitlab.com the domain names must be also specified with the [`gitlab-domains`](06-config.md#gitlab-domains) option. The token must have `api` or `read_api` scope. +Further info can also be found [here](articles/authentication-for-private-packages.md#gitlab-token) ## disable-tls @@ -114,8 +116,8 @@ get a free SSL certificate is generally a better alternative. ## bitbucket-oauth A list of domain names and consumers. For example using `{"bitbucket.org": -{"consumer-key": "myKey", "consumer-secret": "mySecret"}}`. [Read](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html) -how to set up a consumer on Bitbucket. +{"consumer-key": "myKey", "consumer-secret": "mySecret"}}`. +Read more [here](articles/authentication-for-private-packages.md#bitbucket-oauth). ## cafile @@ -134,11 +136,7 @@ capath must be a correctly hashed certificate directory. A list of domain names and username/passwords to authenticate against them. For example using `{"example.org": {"username": "alice", "password": "foo"}}` as the value of this option will let Composer authenticate against example.org. - -> **Note:** Authentication-related config options like `http-basic`, `bearer` and -> `github-oauth` can also be specified inside a `auth.json` file that goes -> besides your `composer.json`. That way you can gitignore it and every -> developer can place their own credentials in there. +More info can be found [here](articles/authentication-for-private-packages.md#http-basic). ## bearer diff --git a/doc/articles/authentication-for-private-packages.md b/doc/articles/authentication-for-private-packages.md index 84107242e..13462e2bc 100644 --- a/doc/articles/authentication-for-private-packages.md +++ b/doc/articles/authentication-for-private-packages.md @@ -1,13 +1,12 @@ -# Authentication for privately hosted packages +# Authentication for privately hosted packages and repositories -Your [private package server](handling-private-packages.md) is probably secured with one +Your [private package server](handling-private-packages.md) or version control system is probably secured with one or more authentication options. In order to allow your project to have access to these -packages you will have to tell Composer how to authenticate with the server that hosts the -package(s). +packages and repositories you will have to tell Composer how to authenticate with the server that hosts them. # Authentication principles @@ -53,6 +52,8 @@ For all authentication methods it is possible to edit them using the command lin - [Inline http-basic](#command-line-inline-http-basic) - [gitlab-oauth](#command-line-gitlab-oauth) - [gitlab-token](#command-line-gitlab-token) + - [github-oauth](#command-line-github-oauth) + - [bitbucket-oauth](#command-line-bitbucket-oauth) ### Manually editing global authentication credentials @@ -71,6 +72,8 @@ For specific authentication implementations, see their sections; - [custom header](#manual-custom-token-authentication) - [gitlab-oauth](#manual-gitlab-oauth) - [gitlab-token](#manual-gitlab-token) + - [github-oauth](#manual-github-oauth) + - [bitbucket-oauth](#manual-bitbucket-oauth) Manually editing this file instead of using the command line may result in invalid json errors. To fix this you need to open the file in an editor and fix the error. To find the location of @@ -97,12 +100,13 @@ 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, +> **Note:** Using the command line environment variable method also has security implications. +> These credentials 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. +> (PowerShell on Windows) when closing a session. The final option to supply Composer with credentials is to use the ```COMPOSER_AUTH``` environment variable. +These variables can be either passed as command line variables or set in actual environment variables. Read more about the usage of this environment variable [here](../03-cli.md#COMPOSER_AUTH). # Authentication methods @@ -217,6 +221,8 @@ composer config [--global] --editor --auth > **Note:** For the gitlab authentication to work on private gitlab instances, the > [`gitlab-domains`](../06-config.md#gitlab-domains) section should also contain the url. +When creating a gitlab token manually, make sure it has either the ```read_api``` or ```api``` scope. + ### Command line gitlab-token ```sh @@ -264,7 +270,7 @@ composer config [--global] --editor --auth ## 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/). +The BitBucket driver uses OAuth to access your private repositories via the BitBucket REST APIs, and you will need to create an OAuth consumer to use the driver, please refer to [Atlassian's Documentation](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/). You will need to fill the callback url with something to satisfy BitBucket, but the address does not need to go anywhere and is not used by Composer. ### Command line bitbucket-oauth From a2c1269488c1235e759df7be533915a4083acc62 Mon Sep 17 00:00:00 2001 From: Jordi Boggiano Date: Wed, 14 Oct 2020 14:41:29 +0200 Subject: [PATCH 3/3] Make linking less verbose --- doc/05-repositories.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/05-repositories.md b/doc/05-repositories.md index 8ce30895d..ff9eeab1e 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -318,8 +318,8 @@ Please note: > **Note that the repository endpoint for BitBucket needs to be https rather than git.** -After setting up your bitbucket repository, you will also need to set up authentication. -Documentation for that [has moved here](articles/authentication-for-private-packages.md#bitbucket-oauth) +After setting up your bitbucket repository, you will also need to +[set up authentication](articles/authentication-for-private-packages.md#bitbucket-oauth). #### Subversion Options