分享方式：

限定範圍的 API 金鑰

  • 文章

若要讓 NuGet 成為更安全的套件發佈環境，您可以透過新增範圍來控制 API 金鑰。

提供 API 金鑰範圍的能力可讓您更好控制 API。 您可以：

  • 建立多個限定範圍的 API 金鑰，以用於不同套件配合不同的到期時間範圍。
  • 安全取得 API 金鑰。
  • 編輯現有的 API 金鑰以變更套件適用性。
  • 重新整理或刪除現有的 API 金鑰，但不使用其他金鑰來阻礙作業。

為什麼支援限定範圍的 API 金鑰？

我們支援限定範圍的 API 金鑰，讓您擁有更細緻的權限。 過去，NuGet 一個帳戶提供一個 API 金鑰，而此方法有幾個缺點：

  • 一個 API 金鑰控制所有套件。 當多位開發人員涉及不同套件且共用一個發佈者帳戶時，使用用於管理所有套件的單一 API 金鑰會難以安全共用金鑰。
  • 所有權限或無權限。 具有 API 金鑰存取權的任何人即擁有套件全部權限 (發佈、推送和取消列出)。 這通常不適合具有多個小組的環境。
  • 單一失敗點。 單一 API 金鑰也表示單一失敗點。 如果金鑰遭到入侵，則所有與該帳戶建立關聯的套件都可能遭到入侵。 重新整理 API 金鑰是防堵洩漏並避免中斷 CI/CD 工作流程的唯一方式。 此外，您也可能想要撤銷個別人士的 API 金鑰存取權 (例如，員工離職時)。 目前沒有清楚的方法可處理此問題。

我們嘗試使用限定範圍的 API 金鑰來解決這些問題，且同時確保現有的工作流程都不中斷。

取得 API 金鑰

  1. 登入您的 nuget.org 帳戶，或如果您還沒有帳戶，請建立帳戶。

  2. 選取右上方的使用者名稱，然後選取 [API 金鑰]。

  3. 選取 [ 建立]，並提供密鑰的名稱。

  4. 在 [選取範圍] 下，選取 [推送]。

  5. 在 [選取套件>Glob 模式] 下，輸入 *。

  6. 選取 建立。

  7. 選取 [ 複製 ] 以複製新的金鑰。

    Screenshot that shows the new API key with the Copy link.

重要

  • 一律將您的 API 金鑰保密。 API 金鑰就像是一種密碼，可讓任何人代表您管理套件。 如果不小心顯示 API 金鑰，請刪除或重新產生您的 API 金鑰。
  • 將您的金鑰儲存在安全的位置，因為您稍後無法再次複製金鑰。 如果您返回 API 金鑰頁面，則需要重新產生金鑰才能加以複製。 如果您不想再推送套件，您也可以移除 API 金鑰。

範圍可讓您針對不同的用途建立個別的 API 金鑰。 每個金鑰都有到期時間範圍，您可以將金鑰範圍設定為特定套件或 glob 模式。 您也會將每個金鑰的範圍設定為特定作業：推送新的套件和套件版本、只推送新的套件版本，或取消列出。

透過範圍界定，您可以為管理組織套件的不同人員建立 API 金鑰，讓他們只擁有所需的許可權。

建立限定範圍的 API 金鑰

您可以根據需求建立多個 API 金鑰。 一個 API 金鑰可以套用至一或多個套件、具有授與特定權限的不同範圍，以及具有與其建立關聯的到期日。

在下列範例中，您擁有名為 Contoso service CI 的 API 金鑰，它可用來推送特定 Contoso.Service 套件的套件，有效期限為 365 天。 這是一般案例：同一組織中有不同小組處理不同的套件，而小組成員獲得的金鑰，僅提供他們處理目前工作中套件的權限。 到期日是避免過期或忘記金鑰的機制。

Create API keys

使用 Glob 模式

如果您要使用多個套件，且有龐大的套件清單要管理，您可以選擇使用萬用字元模式，同時選取多個套件。 例如，如果您想要授與金鑰給所有套件識別碼開頭為 Fabrikam.Service 的特定範圍，您可以在 [Glob 模式] 文字方塊中指定 fabrikam.service.* 來執行此作業。

Create API keys - 2

使用 Glob 模式判斷 API 金鑰權限是否也適用於符合 Glob 模式的套件。 例如，如果您嘗試推送名為 Fabrikam.Service.Framework 的新套件，您可使用先前建立的金鑰完成此作業，因為套件符合 Glob 模式 fabrikam.service.*。

安全取得 API 金鑰

基於安全性，新建立的金鑰絕不會顯示在螢幕中，且只能使用 [複製] 按鈕取得。 同樣地，頁面重新整理後即無法存取金鑰。

Create API keys - 3

編輯現有的 API 金鑰

您可能也想要更新金鑰權限和範圍，但不變更金鑰本身。 如果您的金鑰具有單一套件特定範圍，您可以選擇將相同的範圍套用至一或多個其他套件。

Create API keys - 4

重新整理或刪除現有的 API 金鑰

帳戶擁有者可以選擇重新整理金鑰，如此一來，(套件的) 權限、範圍與到期日將維持不變，但會發出新的金鑰，讓舊的金鑰無法使用。 這有利於管理過時金鑰或有可能外洩的 API 金鑰。

Create API keys - 5

如果不再需要這些金鑰，您也可以選擇刪除它們。 刪除金鑰會移除該金鑰，並讓它無法使用。

常見問題集

舊的 (舊版) API 金鑰會怎麼樣？

您的舊 API 金鑰 (舊版) 會繼續運作，且您想要它運作多久都可以。 不過，如果超過 365 天未使用這些金鑰來推送套件，則會加以淘汰。 如需詳細資料，請參閱部落格文章 Changes to expiring API keys (即將過期 API 金鑰的變更)。 您無法再重新整理此金鑰。 您需要刪除舊版金鑰，改建立新的限定範圍金鑰。

注意

此金鑰具有所有套件的全部權限，且永不過期。 您應該考慮刪除此金鑰，並使用限定範圍的權限和明確到期日來建立新的金鑰。

可以建立幾個 API 金鑰？

您可以建立無數個 API 金鑰。 不過，建議您保持在可管理的計數，以免最後因為過時的金鑰太多，而不知道誰在何處使用它們。

我可以刪除舊版 API 金鑰或立即停止嗎？

是。 您可以 (而且可能應該) 刪除舊版的 API 金鑰。

我可以找回不小心刪除的 API 金鑰嗎？

否。 刪除後，您只能建立新的金鑰。 無法復原意外刪除的金鑰。

重新整理 API 金鑰時，舊的 API 金鑰還會繼續運作嗎？

否。 金鑰一經重新整理就會產生與舊金鑰具有相同範圍、權限和到期日的新金鑰。 舊的金鑰不再存在。

我可以為現有的 API 金鑰授與更多權限嗎？

您無法修改範圍，但您可以編輯它適用的套件清單。

如何知道金鑰過期或即將過期？

如果任何金鑰過期，我們會透過頁面頂端的警告訊息讓您知道。 我們也會在金鑰到期日前十天，向帳戶持有者傳送警告電子郵件，讓您預先採取行動。