Merge pull request #9250 from PrinsFrank/document-authentication-for-private-packages
Document authentication for private packagesmain
Jordi Boggiano
4 years ago
committed by
GitHub
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