Merge pull request #9283 from PrinsFrank/update-authentication-methods-in-documentation
Update authentication methods in documentationpull/9286/head
Jordi Boggiano
GitHub
commit
7e223104c7
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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](articles/authentication-for-private-packages.md#bitbucket-oauth).
|
||||
|
||||
#### Subversion Options
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,13 +1,12 @@
|
|||
<!--
|
||||
tagline: Access privately hosted packages
|
||||
tagline: Access privately hosted packages/repositories
|
||||
-->
|
||||
|
||||
# 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
|
||||
|
||||
|
|
@ -22,6 +21,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.
|
||||
|
|
@ -51,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
|
||||
|
||||
|
|
@ -69,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
|
||||
|
|
@ -93,6 +98,17 @@ 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 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.
|
||||
|
||||
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
|
||||
|
||||
## http-basic
|
||||
|
|
@ -205,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
|
||||
|
|
@ -224,3 +242,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
|
||||
|
||||
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
|
||||
|
||||
```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"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue