composer

mirror of https://github.com/composer/composer

7.8 KiB

Raw Blame History

Authentication for privately hosted packages

Your private package server 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	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.

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
Inline http-basic
gitlab-oauth
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.

To manually edit it, run:

composer config --global --editor [--auth]

For specific authentication implementations, see their sections;

http-basic
Inline http-basic
custom header
gitlab-oauth
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:

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 using the COMPOSER_AUTH environment variable

Note: Using this method also has security implications. Credentials passed using command line environment variables will most likely be stored in memory, and on be persisted to a file like ~/.bash_history(linux) or ConsoleHost_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. Read more about the usage of this environment variable here.

Authentication methods

http-basic

Command line http-basic

composer config [--global] http-basic.example.org username password

Manual http-basic

composer config [--global] --editor --auth

{
    "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

composer config [--global] repositories composer.unique-name https://username:password@repo.example.org

Manual inline http-basic

composer config [--global] --editor

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://username:password@example.org"
        }
    ]
}

Custom token authentication

Manual custom token authentication

composer config [--global] --editor

{
    "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

composer config [--global] gitlab-oauth.example.org token

Manual gitlab-oauth

composer config [--global] --editor --auth

{
    "gitlab-oauth": {
        "example.org": "token"
    }
}

gitlab-token