public-mirrors
/
composer
mirror of https://github.com/composer/composer
1
0
Fork 0
Code

Document authentication for private packages

pull/9250/head
Frank Prins 2020-09-29 21:13:54 +02:00
parent 5df1797d20
commit 45d104ab83
4 changed files with 229 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/05-repositories.md
View File

@ -507,7 +507,7 @@ package repository definitions. It will fetch all the packages that are
`require`d and dump a `packages.json` that is your `composer` repository. `require`d and dump a `packages.json` that is your `composer` repository.
Check [the satis GitHub repository](https://github.com/composer/satis) and Check [the satis GitHub repository](https://github.com/composer/satis) and
the [Satis article](articles/handling-private-packages-with-satis.md) for more the [Satis article](articles/handling-private-packages.md) for more
information. information.
### Artifact ### Artifact

226
doc/articles/authentication-for-private-packages.md Normal file
View File

@ -0,0 +1,226 @@
<!--
tagline: Access privately hosted packages
-->
# Authentication for privately hosted packages
Your [private package server](handling-private-packages.md) 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).
# Authentication principles
Whenever composer encounters a protected composer repository it will try to authenticate
using already defined credentials first. When none of those credentials apply it will prompt
for credentials instead otherwise overridden and save those (or a token if composer is able
to retrieve one).
|type|Generated by Prompt?|
|---|---|
|[http-basic](#http-basic)|yes|
|[Inline http-basic](#inline-http-basic)|no|
|[custom header](#custom-token-authentication)|no|
|[gitlab-oauth](#gitlab-oauth)|yes|
|[gitlab-token](#gitlab-token)|yes|
Sometimes automatic authentication is not possible, or you may want to predefine
authentication credentials.
Credentials can be stored on 3 different places; in an auth.json for the project, a global
auth.json or in the composer.json itself.
## Authentication in auth.json per project
In this authentication storage method, an 'auth.json' file will be present in the same folder
as the projects' composer.json file. You can either create and edit this file using the
command line or manually edit or create it.
> **Note: Make sure the auth.json file is in the .gitignore** otherwise
> other people will be able to abuse your credentials.
## Global authentication credentials
If you don't want to supply credentials for every project you work on, storing your credentials
globally might be a better idea. These credentials are stored in a global auth.json in your
composer home directory.
### Command line global credential editing
For all authentication methods it is possible to edit them using the command line;
- [http-basic](#command-line-http-basic)
- [Inline http-basic](#command-line-inline-http-basic)
- [gitlab-oauth](#command-line-gitlab-oauth)
- [gitlab-token](#command-line-gitlab-token)
### Manually editing global authentication credentials
> **Note:** It is not recommended to manually edit your authentication options as this might
> result in invalid json. Instead preferably use [the command line](#command-line-global-credential-editing).
To manually edit it:
```shell script
composer config --global --editor [--auth]
```
For specific authentication implementations, see their sections;
- [http-basic](#manual-http-basic)
- [Inline http-basic](#manual-inline-http-basic)
- [custom header](#manual-custom-token-authentication)
- [gitlab-oauth](#manual-gitlab-oauth)
- [gitlab-token](#manual-gitlab-token)
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
your global auth.json, execute:
```shell script
composer config --global --list
```
And look for the `[home]` section. (It is by default `~/.composer` or `%APPDATA%/Composer` on Windows)
The folder will contain your global auth.json if it exists.
You can open this file in your favorite editor and fix the error.
## Authentication in composer.json file itself
> **Note:** **This is not recommended** as these credentials are visible
> to anyone who has access to the composer.json, either when it is shared through
> a version control system like git or when an attacker gains (read) access to
> your production server files.
It is also possible to add credentials to a composer.json on a per-project basis in the 'config'
section or directly to the repository definition.
# Authentication methods
## http-basic
### Command line http-basic
```shell script
composer config [--global] http-basic.example.org username password
```
### Manual http-basic
```shell script
composer config [--global] --editor --auth
```
```json
{
"http-basic": {
"example.org": {
"username": "username",
"password": "password"
}
}
}
```
## Inline http-basic
For the inline http-basic authentication method the credentials are not stored in a separate
auth.json in the project or globally, but in the composer.json or global configuration
in the same place where the composer repository definition is defined.
### Command line inline http-basic
```shell script
composer config [--global] repositories composer.unique-name https://username:password@repo.example.org
```
### Manual inline http-basic
```shell script
composer config [--global] --editor
```
```json
{
"repositories": [
{
"type": "composer",
"url": "https://username:password@example.org"
}
]
}
```
## Custom token authentication
### Manual custom token authentication
```shell script
composer config [--global] --editor
```
```json
{
"repositories": [
{
"type": "composer",
"url": "https://example.org",
"options": {
"http": {
"header": [
"API-TOKEN: YOUR-API-TOKEN"
]
}
}
}
]
}
```
## gitlab-oauth
> **Note:** For the gitlab authentication to work on private gitlab instances, the
> "gitlab-domains" section should also contain the url.
### Command line gitlab-oauth
```shell script
composer config [--global] gitlab-oauth.example.org token
```
### Manual gitlab-oauth
```shell script
composer config [--global] --editor --auth
```
```json
{
"gitlab-oauth": {
"example.org": "token"
}
}
```
## gitlab-token
> **Note:** For the gitlab authentication to work on private gitlab instances, the
> "gitlab-domains" section should also contain the url.
### Command line gitlab-token
```shell script
composer config [--global] gitlab-token.example.org token
```
### Manual gitlab-token
```shell script
composer config [--global] --editor --auth
```
```json
{
"gitlab-token": {
"example.org": "token"
}
}
```

19
doc/articles/handling-private-packages-with-satis.md → doc/articles/handling-private-packages.md
View File

@ -213,23 +213,8 @@ Example using a custom HTTP Header field for token authentication:
### Authentication ### Authentication
When your private repositories are password protected, you can store the Authentication can by handled in several different ways. More can be read about it
authentication details permanently. The first time Composer needs to [here](authentication-for-private-packages.md)
authenticate against some domain it will prompt you for a username/password and
then you will be asked whether you want to store it.
The storage can be done either globally in the `COMPOSER_HOME/auth.json` file
(`COMPOSER_HOME` defaults to `~/.composer` or `%APPDATA%/Composer` on Windows)
or also in the project directory directly sitting besides your composer.json.
You can also configure these by hand using the config command if you need to
configure a production machine to be able to run non-interactive installs. For
example to enter credentials for example.org one could type:
composer config http-basic.example.org username password
That will store it in the current directory's auth.json, but if you want it
available globally you can use the `--global` (`-g`) flag.
### Downloads ### Downloads

59
doc/articles/http-basic-authentication.md
View File

@ -1,59 +0,0 @@
<!--
tagline: Access privately hosted packages
-->
# HTTP basic authentication
Your [Satis or Private Packagist](handling-private-packages-with-satis.md) server
could be secured with http basic authentication. In order to allow your project
to have access to these packages you will have to tell composer how to
authenticate with your credentials.
The simplest way to provide your credentials is providing your set
of credentials inline with the repository specification such as:
```json
{
"repositories": [
{
"type": "composer",
"url": "https://extremely:secret@repo.example.org"
}
]
}
```
This will basically teach composer how to authenticate automatically
when reading packages from the provided composer repository.
This does not work for everybody especially when you don't want to
hard code your credentials into your composer.json. There is a second
way to provide these details and it is via interaction. If you don't
provide the authentication credentials composer will prompt you upon
connection to enter the username and password.
The third way if you want to pre-configure it is via an `auth.json` file
located in your `COMPOSER_HOME` or besides your `composer.json`.
The file should contain a set of hostnames followed each with their own
username/password pairs, for example:
```json
{
"http-basic": {
"repo.example1.org": {
"username": "my-username1",
"password": "my-secret-password1"
},
"repo.example2.org": {
"username": "my-username2",
"password": "my-secret-password2"
}
}
}
```
The main advantage of the auth.json file is that it can be gitignored so
that every developer in your team can place their own credentials in there,
which makes revocation of credentials much easier than if you all share the
same.