hryvinskyi / composer-multi-auth

1.1.0 2026-09-09 19:31 UTC

Requires

• php: ^8.1
• composer-plugin-api: ^2.0

Requires (Dev)

• composer/composer: ^2.0

MIT

• Volodymyr Hryvinskyi

Published on Packagist.org on 2026-09-09 19:32 UTC

README

Composer plugin that enables per-package HTTP basic authentication on a single repository domain.

Problem

Composer resolves HTTP basic auth by domain — one credential pair per domain in auth.json. When a single repository hosts packages from different vendors requiring different API keys, there's no native way to use per-package credentials.

How It Works

The plugin reads auth-multi.json from your project root, takes the configured domains out of Composer's own auth handling and authenticates every request to them itself, with exactly one Authorization header per request:

1. Repository markers. A repository registered as https://<name>@domain is served entirely by the rule carrying that name — its packages.json, provider listings and package metadata. The marker is removed from the URL before the request is sent. Register the same host several times with different markers and Composer treats them as independent repositories, each with its own package listing, cache and account, so composer update/require can see packages of every account.
2. Repository discovery of an unmarked repository URL (root packages.json, provider listings and every file they reference by hash) uses the first rule's credentials. Those files are generated per account, so one listing must be fetched with one account.
3. Package downloads (and hash-less per-package metadata) use the first rule whose glob patterns match the package name, then the auth.json credentials of the domain, then the first rule.

First matching rule wins. Use * as a catch-all.

Requirements

• PHP 8.1+
• Composer 2.x

Installation

composer require hryvinskyi/composer-multi-auth

Add to allow-plugins in your composer.json if prompted:

{
    "config": {
        "allow-plugins": {
            "hryvinskyi/composer-multi-auth": true
        }
    }
}

Setup

On first activation the plugin automatically:

• Creates auth-multi.json.sample in the project root
• Adds auth-multi.json to .gitignore

Then create your config:

1. Copy the sample and fill in your keys:

cp auth-multi.json.sample auth-multi.json

1. Edit auth-multi.json:

{
    "http-basic": {
        "private.repo.example.com": {
            "rules": [
                {
                    "patterns": ["acme/*"],
                    "username": "acme-public-key",
                    "password": "acme-private-key"
                },
                {
                    "patterns": ["*"],
                    "username": "your-default-public-key",
                    "password": "your-default-private-key"
                }
            ]
        }
    }
}

Configuration

auth-multi.json

{
    "http-basic": {
        "<domain>": {
            "rules": [
                {
                    "patterns": ["<glob-pattern>", ...],
                    "username": "<public-key>",
                    "password": "<private-key>"
                }
            ]
        }
    }
}

Field	Description
http-basic	Top-level key (matches Composer's auth.json structure)
<domain>	Repository domain
rules	Ordered array of rules — first match wins
name	Optional. Marker that selects this rule for a repository registered as https://<name>@<domain> (letters, digits, ., _, -; unique per domain)
patterns	Array of glob patterns matched via fnmatch() (e.g., vendor/*, vendor/package)
username	HTTP basic auth username / public key
password	HTTP basic auth password / private key

Rule ordering

Rules are evaluated top-to-bottom. The first rule whose patterns match the package name is used. Always place specific rules before the catch-all * rule.

Catch-all rule

The catch-all rule ("patterns": ["*"]) should be the last rule and should contain your default auth.json credentials. This ensures packages not matching any specific rule still authenticate correctly.

Important: For an unmarked repository URL the first rule's credentials are used for repository metadata discovery (loading the package listing). Place the rule for the packages you need to discover first, or register one repository per account (see below).

One repository per account

Register the host once per account, with the rule name as marker in the URL:

{
    "repositories": {
        "magento": {
            "type": "composer",
            "url": "https://[e-mail]"
        },
        "magento-acme": {
            "type": "composer",
            "url": "https://[e-mail]"
        }
    }
}

{
    "http-basic": {
        "repo.magento.com": {
            "rules": [
                {
                    "name": "main",
                    "patterns": ["*"],
                    "username": "main-public-key",
                    "password": "main-private-key"
                },
                {
                    "name": "acme",
                    "patterns": ["acme/*"],
                    "username": "acme-public-key",
                    "password": "acme-private-key"
                }
            ]
        }
    }
}

Composer loads both listings and merges them when resolving; a package offered by several repositories is taken from the one listed first. Package archives carry no marker, so they are matched by patterns — keep a pattern per account for the packages it owns. Metadata caches are kept per marker, so the accounts never share a cached packages.json.

Verification

Run Composer with verbose output to see the plugin in action:

composer install -vvv

Look for [multi-auth] prefixed messages:

Loading plugin Hryvinskyi\ComposerMultiAuth\Plugin
[multi-auth] Loaded rules for 1 domain(s).
[multi-auth] Applying credentials for package "acme/some-package" on "private.repo.example.com".
[multi-auth] Restoring default credentials for package "other/package" on "private.repo.example.com".

License

MIT