Merge pull request #9250 from PrinsFrank/document-authentication-for-private-packages
Document authentication for private packagesmain
commit
53de100721
@ -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 and save them (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 `.gitignore`** to avoid
|
||||||
|
> leaking credentials into your git history.
|
||||||
|
|
||||||
|
## 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, run:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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 in the repository definition.
|
||||||
|
|
||||||
|
# Authentication methods
|
||||||
|
|
||||||
|
## http-basic
|
||||||
|
|
||||||
|
### Command line http-basic
|
||||||
|
|
||||||
|
```sh
|
||||||
|
composer config [--global] http-basic.example.org username password
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual http-basic
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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
|
||||||
|
|
||||||
|
```sh
|
||||||
|
composer config [--global] repositories composer.unique-name https://username:password@repo.example.org
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual inline http-basic
|
||||||
|
|
||||||
|
```sh
|
||||||
|
composer config [--global] --editor
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"repositories": [
|
||||||
|
{
|
||||||
|
"type": "composer",
|
||||||
|
"url": "https://username:password@example.org"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Custom token authentication
|
||||||
|
|
||||||
|
### Manual custom token authentication
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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`](../06-config.md#gitlab-domains) section should also contain the url.
|
||||||
|
|
||||||
|
### Command line gitlab-oauth
|
||||||
|
|
||||||
|
```sh
|
||||||
|
composer config [--global] gitlab-oauth.example.org token
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual gitlab-oauth
|
||||||
|
|
||||||
|
```sh
|
||||||
|
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`](../06-config.md#gitlab-domains) section should also contain the url.
|
||||||
|
|
||||||
|
### Command line gitlab-token
|
||||||
|
|
||||||
|
```sh
|
||||||
|
composer config [--global] gitlab-token.example.org token
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual gitlab-token
|
||||||
|
|
||||||
|
```sh
|
||||||
|
composer config [--global] --editor --auth
|
||||||
|
```
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"gitlab-token": {
|
||||||
|
"example.org": "token"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
@ -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.
|
|
Loading…
Reference in New Issue