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

發行項
04/03/2023

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

Azure 金鑰保存庫秘密用戶端程式庫可讓您安全地儲存和控制權杖、密碼、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 金鑰保存庫秘密服務相關工作：

非同步範例

以非同步方式建立秘密
以非同步方式列出秘密
以非同步方式刪除秘密

建立祕密

SetSecret會 KeyVaultSecret 建立要儲存在 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 金鑰保存庫秘密的範例程式碼，包括：
- 建立秘密
- 列出金鑰保存庫中的所有秘密
- 更新金鑰保存庫中的秘密
- 列出指定秘密的版本
- 從金鑰保存庫中刪除秘密
- 列出金鑰保存庫中刪除的秘密

其他文件

如需 Azure 金鑰保存庫的詳細資訊檔，請參閱API 參考檔。
如需金鑰用戶端程式庫，請參閱金鑰用戶端程式庫。
如需憑證用戶端程式庫，請參閱憑證用戶端程式庫。

參與

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

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

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

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

曝光數