共用方式為


適用于 .NET 的 Azure 金鑰保存庫秘密用戶端程式庫 - 4.5.0 版

Azure 金鑰保存庫是一種雲端服務,可提供安全的秘密儲存體,例如密碼和資料庫連接字串。

Azure 金鑰保存庫秘密用戶端程式庫可讓您安全地儲存和控制權杖、密碼、API 金鑰和其他秘密的存取。 此程式庫提供建立、擷取、更新、刪除、清除、備份、還原,以及列出秘密及其版本的作業。

| 原始程式碼套件 (NuGet) | API 參考檔 | 產品檔 | 樣品 | 移轉指南

開始使用

安裝套件

使用NuGet安裝適用于 .NET 的 Azure 金鑰保存庫秘密用戶端程式庫:

dotnet add package Azure.Security.KeyVault.Secrets

必要條件

  • Azure 訂用帳戶
  • 現有的 Azure 金鑰保存庫。 如果您需要建立 Azure 金鑰保存庫,您可以使用 Azure 入口網站或Azure CLI
  • 使用RBAC (建議) 或存取控制,授權現有 Azure 金鑰保存庫。

如果您使用 Azure CLI,請將 和 <your-key-vault-name> 取代 <your-resource-group-name> 為您自己的唯一名稱:

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

驗證用戶端

若要與 Azure 金鑰保存庫服務互動,您必須建立SecretClient類別的實例。 您需要保存 庫 URL,您可能會在入口網站中看到「DNS 名稱」,以及具現化用戶端物件的認證。

以下顯示的範例會使用 DefaultAzureCredential ,適用于大部分的案例,包括本機開發和生產環境。 此外,我們建議在生產環境中使用受控識別進行驗證。 您可以在 Azure 身分識別 檔中找到不同驗證方式及其對應認證類型的詳細資訊。

若要使用 DefaultAzureCredential 如下所示的提供者,或其他隨附于 Azure SDK 的認證提供者,您必須先安裝 Azure.Identity 套件:

dotnet add package Azure.Identity

將 具現化 DefaultAzureCredential 以傳遞至用戶端。 如果權杖認證會使用相同的身分識別進行驗證,則相同的權杖認證實例可以與多個用戶端搭配使用。

// Create a new secret client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new SecretClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new secret using the secret client.
KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

// Retrieve a secret using the secret client.
secret = client.GetSecret("secret-name");

重要概念

KeyVaultSecret

KeyVaultSecret Azure 金鑰保存庫內的基本資源。 從開發人員的觀點來看,Azure 金鑰保存庫 API 接受並傳回秘密值作為字串。

SecretClient

提供 SecretClient SDK 中的同步和非同步作業,允許根據應用程式的使用案例來選取用戶端。 初始化 SecretClient 之後,您就可以與 Azure 金鑰保存庫中的秘密互動。

執行緒安全

我們保證所有用戶端實例方法都是安全線程,且彼此獨立 (指導方針) 。 這可確保重複使用用戶端實例的建議一律是安全的,即使是跨執行緒也一樣。

其他概念

用戶端選項 | 存取回應 | 長時間執行的作業 | 處理失敗 | 診斷 | 嘲笑 | 用戶端存留期

範例

Azure.Security.KeyVault.Secrets 套件支援同步和非同步 API。

下一節提供使用上述建立的數個程式碼片段 client ,涵蓋一些最常見的 Azure 金鑰保存庫秘密服務相關工作:

同步範例

非同步範例

建立祕密

SetSecretKeyVaultSecret 建立要儲存在 Azure 金鑰保存庫中的 。 如果具有相同名稱的秘密已經存在,則會建立新版本的秘密。

KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);
Console.WriteLine(secret.Properties.Version);
Console.WriteLine(secret.Properties.Enabled);

擷取祕密

GetSecret擷取先前儲存在 Azure 金鑰保存庫中的秘密。

KeyVaultSecret secret = client.GetSecret("secret-name");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

更新現有的秘密

UpdateSecretProperties會更新先前儲存在 Azure 金鑰保存庫中的秘密。 只會更新秘密的屬性。 若要更新值,請在具有相同名稱的秘密上呼叫 SecretClient.SetSecret

KeyVaultSecret secret = client.GetSecret("secret-name");

// Clients may specify the content type of a secret to assist in interpreting the secret data when its retrieved.
secret.Properties.ContentType = "text/plain";

// You can specify additional application-specific metadata in the form of tags.
secret.Properties.Tags["foo"] = "updated tag";

SecretProperties updatedSecretProperties = client.UpdateSecretProperties(secret.Properties);

Console.WriteLine(updatedSecretProperties.Name);
Console.WriteLine(updatedSecretProperties.Version);
Console.WriteLine(updatedSecretProperties.ContentType);

刪除祕密

StartDeleteSecret會啟動長時間執行的作業,以刪除先前儲存在 Azure 金鑰保存庫 中的秘密。 您可以立即擷取秘密,而不需要等待作業完成。 當 Azure 金鑰保存庫未啟用虛刪除時,此作業會永久刪除秘密。

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

DeletedSecret secret = operation.Value;
Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

刪除和清除秘密

您必須等待長時間執行的作業完成,才能嘗試清除或復原秘密。 您可以藉由在迴圈中呼叫 UpdateStatus 來執行此動作,如下所示:

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

// You only need to wait for completion if you want to purge or recover the secret.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedSecret secret = operation.Value;
client.PurgeDeletedSecret(secret.Name);

列出密碼

本範例會列出指定之 Azure 金鑰保存庫中的所有秘密。 列出所有秘密時,不會傳回值。 您必須呼叫 SecretClient.GetSecret 以擷取值。

Pageable<SecretProperties> allSecrets = client.GetPropertiesOfSecrets();

foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

以非同步方式建立秘密

非同步 API 與其同步對應專案相同,但會傳回非同步方法的一般 「Async」 尾碼,並傳回 Task

此範例會使用指定的選擇性引數,在 Azure 金鑰保存庫中建立秘密。

KeyVaultSecret secret = await client.SetSecretAsync("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

以非同步方式列出秘密

列出秘密不依賴等候 GetPropertiesOfSecretsAsync 方法,但會傳回 AsyncPageable<SecretProperties> 您可以搭配 await foreach 語句使用的 :

AsyncPageable<SecretProperties> allSecrets = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

以非同步方式刪除秘密

在清除秘密之前,以非同步方式刪除秘密時,您可以等候 WaitForCompletionAsync 作業上的 方法。 根據預設,此迴圈會無限期地執行,但您可以傳遞 CancellationToken 來取消它。

DeleteSecretOperation operation = await client.StartDeleteSecretAsync("secret-name");

// You only need to wait for completion if you want to purge or recover the secret.
await operation.WaitForCompletionAsync();

DeletedSecret secret = operation.Value;
await client.PurgeDeletedSecretAsync(secret.Name);

疑難排解

如需如何診斷各種失敗案例的詳細資訊,請參閱我們的 疑難排解指南

一般

當您使用 .NET SDK 與 Azure 金鑰保存庫秘密用戶端程式庫互動時,服務傳回的錯誤會對應至針對 REST API要求傳回的相同 HTTP 狀態碼。

例如,如果您嘗試擷取 Azure 金鑰保存庫中不存在的秘密, 404 則會傳回錯誤,表示 Not Found

try
{
    KeyVaultSecret secret = client.GetSecret("some_secret");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

您會注意到會記錄其他資訊,例如作業的用戶端要求識別碼。

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"SecretNotFound","message":"Secret not found: some_secret"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

下一步

此 GitHub 存放庫中有數個 Azure 金鑰保存庫秘密用戶端程式庫範例可供您使用。 這些範例提供使用 Azure 金鑰保存庫時常遇到的其他案例範例程式碼:

  • Sample1_HelloWorld.md - 用於使用 Azure 金鑰保存庫,包括:

    • 建立祕密
    • 取得現有的秘密
    • 更新現有的秘密
    • 刪除祕密
  • Sample2_BackupAndRestore.md - 包含使用 Azure 金鑰保存庫秘密的程式碼片段,包括:

    • 備份和復原秘密
  • Sample3_GetSecrets.md - 使用 Azure 金鑰保存庫秘密的範例程式碼,包括:

    • 建立秘密
    • 列出金鑰保存庫中的所有秘密
    • 更新金鑰保存庫中的秘密
    • 列出指定秘密的版本
    • 從金鑰保存庫中刪除秘密
    • 列出金鑰保存庫中刪除的秘密

其他文件

參與

如需建 、測試及參與這些程式庫的詳細資訊,請參閱 CONTRIBUTING.md。

此專案歡迎參與和提供建議。 大部分的參與都要求您同意「參與者授權合約 (CLA)」,宣告您有權且確實授與我們使用投稿的權利。 如需詳細資料,請前往 https://cla.microsoft.com

當您提交提取要求時,CLA Bot 會自動判斷您是否需要提供 CLA,並適當地裝飾 PR (例如標籤、註解)。 請遵循 bot 提供的指示。 您只需要使用我們的 CLA 在所有存放庫上執行此動作一次。

此專案採用 Microsoft Open Source Code of Conduct (Microsoft 開放原始碼管理辦法)。 如需詳細資訊,請參閱管理辦法常見問題集,如有任何其他問題或意見請連絡 opencode@microsoft.com。

曝光數