私人託管套件及儲存庫的驗證#

您的 私人套件伺服器 或版本控管系統可能會啟用一或多種驗證選項以進行保護。為讓您的專案存取這些套件及儲存庫，您必須告知 Composer 如何向託管這些資源的伺服器進行驗證。

驗證原則#

偵測到受保護的 Composer 儲存庫時，Composer 會先嘗試使用已定義的憑證進行驗證。如果未取得任何適用憑證，就會提示輸入憑證並儲存（如果 Composer 能夠取得的話，則儲存令牌）。

類型	是否經提示生成？
http-basic	是
內嵌式 http-basic	否
HTTP Bearer	否
自訂標頭	否
gitlab-oauth	是
gitlab-token	是
github-oauth	是
bitbucket-oauth	是

有時無法進行自動驗證，或者您可能想預先定義驗證憑證。

憑證可以儲存在 4 個不同的地方：專案的 auth.json、全域 auth.json、composer.json 本身或 COMPOSER_AUTH 環境變數中。

auth.json 中的專案驗證#

針對此驗證儲存法，auth.json 檔案會放置於與專案 composer.json 檔案相同的資料夾。您可以透過指令列或手動建立並編輯此檔案。

注意：確認放置 auth.json 檔案在 .gitignore 中，避免憑證外洩到您的 git 歷程中。

全域驗證憑證#

如果您不想要針對每個所參與的專案提供憑證，採用全域憑證儲存方式會是個更好的主意。這些憑證會儲存在 Composer 主目錄中的全域 auth.json。

指令列全域憑證編輯#

使用指令列可以編輯所有驗證方法；

• http-basic
• 內嵌式 http-basic
• HTTP Bearer
• gitlab-oauth
• gitlab-token
• github-oauth
• bitbucket-oauth

手動編輯全域認證憑證#

注意：不建議手動編輯認證選項，因為這樣可能會導致 JSON 無效。建議使用命令列。

若要手動編輯，請執行

php composer.phar config --global --editor [--auth]

有關特定認證實作，請參閱相關區段；

• http-basic
• 內嵌式 http-basic
• HTTP Bearer
• 自訂標頭
• gitlab-oauth
• gitlab-token
• github-oauth
• bitbucket-oauth

手動編輯此檔案，而不是使用命令列，可能會導致 JSON 無效錯誤。要修復此問題，您需要在編輯器中開啟檔案並修復錯誤。若要找出全域 auth.json 的位置，請執行

php composer.phar config --global home

如果資料夾存在，則會包含您的全域 auth.json。

您可以在您最愛的編輯器中開啟此檔案並修復錯誤。

composer.json 檔案本身的認證#

注意：不建議這樣做，因為任何有權存取 composer.json 的人（無論是透過版本控制系統（如 git）分享，或攻擊者獲得對您製作伺服器檔案的（讀取）存取權）都可以看到這些憑證。

您也可以在專案基礎的 composer.json 的 config 區段中，或直接在儲存庫定義中，新增憑證。

使用 COMPOSER_AUTH 環境變數進行認證#

注意：使用命令列環境變數方法也會有安全性影響。這些憑證極有可能儲存在記憶體中，而且在關閉工作階段時，可能會持續存在於 ~/.bash_history (linux) 或 ConsoleHost_history.txt (Windows 上的 PowerShell) 之類的檔案中。

提供 Composer 憑證的最後一個選項是使用 COMPOSER_AUTH 環境變數。這些變數可以傳遞為命令列變數或設定為實際的環境變數。在此處閱讀有關此環境變數使用的更多資訊在此處。

認證方法#

http-basic#

命令列 http-basic#

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

在以上指令中，組態金鑰 http-basic.repo.example.org 包含兩個部分

• http-basic 是認證方法。
• repo.example.org 是儲存庫主機名稱，您應該將它取代為您的儲存庫的主機名稱。

手動 http-basic#

php composer.phar config [--global] --editor --auth

{
    "http-basic": {
        "example.org": {
            "username": "username",
            "password": "password"
        }
    }
}

內嵌 http-basic#

針對內嵌 http-basic 認證方法，憑證不會儲存在專案或全域的獨立 auth.json 中，而是儲存在與定義 Composer 儲存庫定義相同位置的 composer.json 或全域組態中。

請確定使用者名稱和密碼根據RFC 3986（2.1 百分號編碼）進行編碼。如果使用者名稱例如是電子郵件地址，則需要傳遞為 name%40example.com。

命令列內嵌 http-basic#

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

手動內嵌 http-basic#

php composer.phar config [--global] --editor

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

HTTP 載體#

HTTP 載體驗證的命令列#

php composer.phar config [--global] bearer.repo.example.org token

在以上命令中，設定金鑰 bearer.repo.example.org 包含兩個部分

• bearer 是驗證方式。
• repo.example.org 是儲存庫主機名稱，您應該將它取代為您的儲存庫的主機名稱。

手動 HTTP 載體驗證#

php composer.phar config [--global] --editor --auth

{
    "bearer": {
        "example.org": "TOKEN"
    }
}

自訂トークン驗證#

手動自訂トークン驗證#

php composer.phar config [--global] --editor

{
    "repositories": [
        {
            "type": "composer",
            "url": "https://example.org",
            "options":  {
                "http": {
                    "header": [
                        "API-TOKEN: YOUR-API-TOKEN"
                    ]
                }
            }
        }
    ]
}

gitlab-oauth#

注意：要讓 gitlab 驗證在私人 gitlab 個體執行，gitlab-domains 部分也應該包含網址。

gitlab-oauth 的命令列#

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

在以上命令中，設定金鑰 gitlab-oauth.gitlab.example.org 包含兩個部分

• gitlab-oauth 是驗證方式。
• gitlab.example.org 是 GitLab 個體的主機名稱，您應該以 GitLab 個體的主機名稱取代，或者如果您沒有自架的 GitLab 個體，就使用 gitlab.com。14

手動 gitlab-oauth#

php composer.phar config [--global] --editor --auth

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

gitlab-token#

注意：要讓 gitlab 驗證在私人 gitlab 個體執行，gitlab-domains 部分也應該包含網址。

要建立新的存取權杖，前往 GitLab 上的 存取權杖部分（或您私人個體上的等效網址），並建立新的權杖。另請參閱 GitLab 存取權杖文件 以取得更多資訊。

在手動建立 gitlab 權杖時，確認它已具有 read_api 或 api 範圍。

gitlab-token 的命令列#

php composer.phar config [--global] gitlab-token.gitlab.example.org token

在以上命令中，設定金鑰 gitlab-token.gitlab.example.org 包含兩個部分

• gitlab-token 是驗證方式。
• gitlab.example.org 是 GitLab 個體的主機名稱，您應該以 GitLab 個體的主機名稱取代，或者如果您沒有自架的 GitLab 個體，就使用 gitlab.com。14

手動 gitlab-token#

php composer.phar config [--global] --editor --auth

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

github-oauth#

要建立新的存取權杖，前往 Github 上的 權杖設定部分，並 產生新的權杖。

在有速率限制的公開儲存庫時，沒有任何特定範圍的權杖就已足夠（請參閱 範圍文件 中的 (no scope)）。此類權杖授予唯讀權限以取得公開資訊。

對於私人的儲存庫，需要repo範圍。請注意，令牌將獲得廣泛的讀取/寫入權限才能存取您所有私人儲存庫以及更多內容，請參閱範圍文件的說明以取得完整清單。截至編寫本文（2021 年 11 月），似乎無法進一步限制此類令牌的權限。

進一步了解 個人存取權杖，或訂閱 GitHub中作用域令牌的路線圖項目。

命令列 github-oauth#

php composer.phar config [--global] github-oauth.github.com token

在上述命令中，設定檔金鑰github-oauth.github.com包含兩部分

• github-oauth是驗證方法。
• github.com為此令牌套用之主機名稱。對於 GitHub，您很可能不需要變更這個名稱。

手動設定 github-oauth#

php composer.phar config [--global] --editor --auth

{
    "github-oauth": {
        "github.com": "token"
    }
}

bitbucket-oauth#

BitBucket 驅動程式會透過 BitBucket REST API 使用 OAuth 存取您的私人儲存庫，您將需要建立 OAuth 使用者端才能使用驅動程式，請參閱 Atlassian 的說明文件。您需要填寫回呼網址來滿足 BitBucket，但 Composer 並不使用此網址，所以您填寫任何網址即可。

命令列 bitbucket-oauth#

php composer.phar config [--global] bitbucket-oauth.bitbucket.org consumer-key consumer-secret

在上述命令中，設定檔金鑰bitbucket-oauth.bitbucket.org包含兩部分

• bitbucket-oauth是驗證方法。
• bitbucket.org為此令牌套用之主機名稱。除非您有私人實例，否則您不需要變更這個名稱。

手動設定 bitbucket-oauth#

php composer.phar config [--global] --editor --auth

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

發現錯字了嗎？這份文件有什麼不對勁的地方嗎？分岔並編輯文件吧！