Raydium

Appearance

Auth Configuration ​

managing multiple credentials in your auth.json for Composer.

📑 Table of Contents ​

  1. Overview

  2. File Locations

  3. auth.json Structure

  4. Adding Credentials via CLI

  5. Managing Entries

  6. Best Practices

  7. Troubleshooting & FAQ

Overview ​

Composer uses an auth.json file to store credentials for private repositories and package hosts. You can keep multiple credentials—HTTP basic, OAuth tokens, personal access tokens, etc.—in one central file, keyed by host. This keeps your composer.json clean and your secrets out of your project manifests.

File Locations ​

ContextPath
GlobalLinux/macOS: ~/.composer/auth.json
Windows: %APPDATA%\Composer\auth.json
Project‑local<project-root>/auth.json

Tip:

  • Use project‑local for project‑specific tokens (e.g., a repo‑only deploy key).
  • Use global for personal access tokens you reuse across projects.

auth.json Structure ​

Your auth.json is a JSON object with credential types as top‑level keys. Each type maps hostnames → credential data.

json
{
  "http-basic":   { /* Basic HTTP auth */ },
  "github-oauth": { /* GitHub tokens */ },
  "gitlab-token": { /* GitLab PATs */ },
  "bitbucket-oauth": { /* Bitbucket OAuth */ },
  "bearer":       { /* Bearer tokens (npm, etc.) */ }
}

HTTP Basic Auth ​

For Composer repos that require user/pass:

json
"http-basic": {
  "repo1.example.com": {
    "username": "alice",
    "password": "s3cret!"
  },
  "repo2.example.com": {
    "username": "bob",
    "password": "P@ssw0rd"
  }
}

GitHub OAuth ​

For GitHub’s API rate limits or private repos:

json
"github-oauth": {
  "github.com":                   "ghp_abcd1234ABCDEFGHIJKLMNOP",
  "github.enterprise.local":      "ghp_enterprisetoken09876ZYXWV"
}

GitLab Token ​

GitLab personal access tokens:

json
"gitlab-token": {
  "gitlab.com":              "glpat-ABCDEFGHIJKLMNOPQRSTU",
  "git.self-hosted.local":   "glpat-1234567890ABCDEFGHIJ"
}

Bitbucket OAuth ​

Consumer key/secret pairs:

json
"bitbucket-oauth": {
  "bitbucket.org": {
    "consumer-key":    "KEY12345",
    "consumer-secret": "SECRET67890"
  }
}

Bearer Tokens ​

Generic bearer tokens (e.g., npm registries):

json
"bearer": {
  "npm.pkg.github.com": "npm_abcdefghijklmnopqrstuv"
}

Adding Credentials via CLI ​

Avoid hand‑editing—use Composer’s built‑in config command to keep JSON valid.

bash
# 1. HTTP Basic
composer config --global http-basic.repo1.example.com    alice   s3cret!
composer config --global http-basic.repo2.example.com    bob     P@ssw0rd

# 2. GitHub OAuth
composer config --global github-oauth.github.com         ghp_abcd1234ABCDEFGHIJKLMNOP
composer config --global github-oauth.github.enterprise.local ghp_enterprisetoken09876ZYXWV

# 3. GitLab Token
composer config --global gitlab-token.gitlab.com         glpat-ABCDEFGHIJKLMNOPQRSTU
composer config --global gitlab-token.git.self-hosted.local glpat-1234567890ABCDEFGHIJ

# 4. Bitbucket OAuth
composer config --global bitbucket-oauth.bitbucket.org.consumer-key    KEY12345  
composer config --global bitbucket-oauth.bitbucket.org.consumer-secret SECRET67890

# 5. Bearer Token
composer config --global bearer.npm.pkg.github.com       npm_abcdefghijklmnopqrstuv

These commands will automatically create or update your global auth.json.

Managing Entries ​

  • List current credentials:

    bash
    cat ~/.composer/auth.json | jq .

  • Remove an entry:

    bash
    composer config --global --unset http-basic.repo1.example.com

  • Migrate global → project:

    1. Copy the relevant block from ~/.composer/auth.json.
    2. Paste into <project>/auth.json under the same key.

Best Practices ​

  • Never commit auth.json to Git.
  • Store least-privilege tokens (scoped to repos/services).
  • Rotate tokens periodically.
  • Use project‑local tokens for CI/CD pipelines.
  • Document in your README if private repos require extra setup.

Troubleshooting & FAQ ​

Q: Composer still prompts for credentials—what gives? A:

  1. Check you have the correct hostname (no trailing slash, exact match).
  2. Verify JSON syntax (jq . auth.json).
  3. Ensure you’re editing the right file (COMPOSER_HOME vs. project).

Q: I have a GitHub token but hit API rate limits. A:

  • Ensure token has repo and read:packages scopes.
  • Use a fine‑grained token for public/open‑source to reduce scope.

Q: Can I use the same token for GitHub and GitHub Enterprise? A: Yes—just add separate entries under github-oauth with each hostname.