Your private package server 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 and repositories you will have to tell Composer how to authenticate with the server that hosts them.
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 | yes |
| Inline http-basic | no |
| Custom header | no |
| gitlab-oauth | yes |
| gitlab-token | yes |
| github-oauth | yes |
| bitbucket-oauth | 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.
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.jsonfile is in.gitignoreto avoid leaking credentials into your git history.
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.
For all authentication methods it is possible to edit them using the command line;
Note: It is not recommended to manually edit your authentication options as this might result in invalid json. Instead preferably use the command line.
To manually edit it, run:
composer config --global --editor [--auth]For specific authentication implementations, see their sections;
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:
composer config --global homeThe folder will contain your global auth.json if it exists.
You can open this file in your favorite editor and fix the error.
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.
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) orConsoleHost_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.
composer config [--global] http-basic.example.org username passwordcomposer config [--global] --editor --auth{
"http-basic": {
"example.org": {
"username": "username",
"password": "password"
}
}
}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.
Make sure that the username and password are encoded according to RFC 3986 (2.1. Percent-Encoding).
If the username e.g. is an email address it needs to be passed as name%40example.com.
composer config [--global] repositories composer.unique-name https://username:[email protected]composer config [--global] --editor{
"repositories": [
{
"type": "composer",
"url": "https://username:[email protected]"
}
]
}composer config [--global] --editor{
"repositories": [
{
"type": "composer",
"url": "https://example.org",
"options": {
"http": {
"header": [
"API-TOKEN: YOUR-API-TOKEN"
]
}
}
}
]
}Note: For the gitlab authentication to work on private gitlab instances, the
gitlab-domainssection should also contain the url.
composer config [--global] gitlab-oauth.example.org tokencomposer config [--global] --editor --auth{
"gitlab-oauth": {
"example.org": "token"
}
}Note: For the gitlab authentication to work on private gitlab instances, the
gitlab-domainssection should also contain the url.
When creating a gitlab token manually, make sure it has either the read_api or api scope.
composer config [--global] gitlab-token.example.org tokencomposer config [--global] --editor --auth{
"gitlab-token": {
"example.org": "token"
}
}To create a new access token, head to your token settings section on Github and generate a new token. 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.
composer config [--global] github-oauth.github.com tokencomposer config [--global] --editor --auth{
"github-oauth": {
"github.com": "token"
}
}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. 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.
composer config [--global] bitbucket-oauth.bitbucket.org consumer-key consumer-secretcomposer config [--global] --editor --auth{
"bitbucket-oauth": {
"bitbucket.org": {
"consumer-key": "key",
"consumer-secret": "secret"
}
}
}