composer/doc/articles/authentication-for-private-packages.md

<!--
    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"
    }
}
```