From 45d104ab832e2c32ccbcf78ebe19ab5946ffd9d9 Mon Sep 17 00:00:00 2001 From: Frank Prins <25006490+PrinsFrank@users.noreply.github.com> Date: Tue, 29 Sep 2020 21:13:54 +0200 Subject: [PATCH] Document authentication for private packages --- doc/05-repositories.md | 2 +- .../authentication-for-private-packages.md | 226 ++++++++++++++++++ ...-satis.md => handling-private-packages.md} | 19 +- doc/articles/http-basic-authentication.md | 59 ----- 4 files changed, 229 insertions(+), 77 deletions(-) create mode 100644 doc/articles/authentication-for-private-packages.md rename doc/articles/{handling-private-packages-with-satis.md => handling-private-packages.md} (92%) delete mode 100644 doc/articles/http-basic-authentication.md diff --git a/doc/05-repositories.md b/doc/05-repositories.md index 12a9dced0..38b5ef6f5 100644 --- a/doc/05-repositories.md +++ b/doc/05-repositories.md @@ -507,7 +507,7 @@ package repository definitions. It will fetch all the packages that are `require`d and dump a `packages.json` that is your `composer` repository. Check [the satis GitHub repository](https://github.com/composer/satis) and -the [Satis article](articles/handling-private-packages-with-satis.md) for more +the [Satis article](articles/handling-private-packages.md) for more information. ### Artifact diff --git a/doc/articles/authentication-for-private-packages.md b/doc/articles/authentication-for-private-packages.md new file mode 100644 index 000000000..3201d3269 --- /dev/null +++ b/doc/articles/authentication-for-private-packages.md @@ -0,0 +1,226 @@ + + +# 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" + } +} +``` diff --git a/doc/articles/handling-private-packages-with-satis.md b/doc/articles/handling-private-packages.md similarity index 92% rename from doc/articles/handling-private-packages-with-satis.md rename to doc/articles/handling-private-packages.md index 3ef604fe7..026097b2d 100644 --- a/doc/articles/handling-private-packages-with-satis.md +++ b/doc/articles/handling-private-packages.md @@ -213,23 +213,8 @@ Example using a custom HTTP Header field for token authentication: ### Authentication -When your private repositories are password protected, you can store the -authentication details permanently. The first time Composer needs to -authenticate against some domain it will prompt you for a username/password and -then you will be asked whether you want to store it. - -The storage can be done either globally in the `COMPOSER_HOME/auth.json` file -(`COMPOSER_HOME` defaults to `~/.composer` or `%APPDATA%/Composer` on Windows) -or also in the project directory directly sitting besides your composer.json. - -You can also configure these by hand using the config command if you need to -configure a production machine to be able to run non-interactive installs. For -example to enter credentials for example.org one could type: - - composer config http-basic.example.org username password - -That will store it in the current directory's auth.json, but if you want it -available globally you can use the `--global` (`-g`) flag. +Authentication can by handled in several different ways. More can be read about it +[here](authentication-for-private-packages.md) ### Downloads diff --git a/doc/articles/http-basic-authentication.md b/doc/articles/http-basic-authentication.md deleted file mode 100644 index fad17d28f..000000000 --- a/doc/articles/http-basic-authentication.md +++ /dev/null @@ -1,59 +0,0 @@ - - -# 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.