Azure.Security.KeyVault.Secrets 4.6.0

Azure Key Vault 密钥客户端库用于 .NET

Azure Key Vault 是一种云服务，它提供对密码和数据库连接字符串等机密的安全存储。

Azure Key Vault 密钥客户端库允许您安全地存储和控制系统访问令牌、密码、API密钥和其他机密。此库提供了用于创建、检索、更新、删除、清除、备份、恢复和列出密钥及其版本的运算。

源代码 | 包（NuGet） | API 文档参考 | 产品文档 | 示例 | 迁移指南

入门

安装包

使用 NuGet 安装 Azure Key Vault 密钥客户端库用于 .NET

dotnet add package Azure.Security.KeyVault.Secrets

先决条件

• 一个Azure订阅。
• 现有的Azure Key Vault。如果您需要创建Azure Key Vault，可以使用Azure门户或Azure CLI。
• 使用RBAC（推荐）或访问控制授权访问现有的Azure Key Vault。

如果您使用Azure CLI，请将<your-resource-group-name>和<your-key-vault-name>替换为您自己的、唯一的名称。

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

认证客户端

为了与Azure Key Vault服务交互，您需要创建SecretClient类的实例。您需要一个保管库URL，这可能在门户中显示为“DNS名称”，以及用于实例化客户端对象的凭据。

下面的示例使用了DefaultAzureCredential，适用于包括本地开发和生产环境在内的大多数场景。此外，我们建议在生产环境中使用托管身份进行身份验证。有关不同身份验证方式和相应凭据类型的更多信息，请参阅Azure Identity文档。

要使用下面的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 Key Vault中的基本资源。从开发者的角度来看，Azure Key Vault API接受并返回字符串格式的密钥值。

SecretClient

SecretClient提供SDK中的同步和异步操作，允许根据应用程序的使用场景选择客户端。初始化SecretClient后，您就可以与Azure Key Vault中的密钥进行交互了。

线程安全

我们保证所有客户端实例方法都是线程安全的且彼此独立（《线程安全指南》）。这确保了重用客户端实例的建议总是安全的，即使在跨线程的情况下。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 模拟 | 客户端生命周期

示例

Azure.Security.KeyVault.Secrets包支持同步和异步API。

以下部分提供了使用上述创建的client的几个代码片段，覆盖了某些最常见的Azure Key Vault密钥服务相关任务。

同步示例

• 创建密钥
• 检索密钥
• 更新现有密钥
• 删除密钥
• 删除并清除密钥
• 列密钥

异步示例

• 异步创建密钥
• 异步列密钥
• 异步删除秘密

创建密钥

SetSecret创建一个用于在Azure Key Vault中存储的KeyVaultSecret。如果已存在具有相同名称的秘密，则创建秘密的新版本。

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 Key Vault检索先前存储的秘密。

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

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

更新现有密钥

UpdateSecretProperties更新Azure Key Vault中先前存储的秘密。仅更新秘密的属性。要更新值，请在具有相同名称的秘密上调用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 Key Vault中先前存储的秘密。您可以在操作完成之前立即检索秘密。当Azure Key Vault未启用软删除时，此操作将永久删除秘密。

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 Key Vault中的所有秘密。列出所有秘密时，不会返回值。您需要调用SecretClient.GetSecret来检索值。

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

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

异步创建密钥

异步API与其同步版本相同，但异步方法以典型的"Async"后缀返回，并返回一个Task。

此示例使用指定的可选参数在Azure Key Vault中创建一个秘密。

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

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

异步列密钥

列出秘密不需要等待GetPropertiesOfSecretsAsync方法，但返回一个可用于await foreach语句的AsyncPageable<SecretProperties>。

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 Key Vault秘密客户端库交互时，服务返回的错误对应于REST API请求返回的相同HTTP状态码。

例如，如果您尝试检索Azure Key Vault中不存在的秘密，则返回一个404错误，表示Not Found（未找到）。

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

您将注意到记录了附加信息，例如操作的Client请求ID。

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 Key Vault秘密客户端库的几个示例。这些示例提供了处理Azure Key Vault时遇到的常见场景的示例代码。

• Sample1_HelloWorld.md - 用于处理Azure Key Vault，包括

  • 创建密钥
  • 获取现有秘密
  • 更新现有密钥
  • 删除秘密

• Sample2_BackupAndRestore.md - 包含处理Azure Key Vault秘密的代码片段，包括

  • 备份和恢复秘密

• Sample3_GetSecrets.md - 用于处理Azure Key Vault秘密的示例代码，包括

  • 创建秘密
  • 列出Key Vault中的所有秘密
  • 更新Key Vault中的秘密
  • 列出指定秘密的版本
  • 从Key Vault中删除秘密
  • 列出Key Vault中的已删除秘密

其他文档

• 有关Azure Key Vault的更多详细信息，请参阅API参考文档.
• 有关密钥客户端库，请参阅Keys客户端库.
• 有关证书客户端库，请参阅Certificates客户端库.

贡献

有关构建、测试和贡献这些库的详细信息，请参阅CONTRIBUTING.md.

本项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您拥有并可授予我们使用您贡献的权利。有关详细信息，请访问https://cla.microsoft.com.

在提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并相应地对PR进行装饰（例如，标签、注释）。只需遵循机器人提供的说明。您将只需在整个使用我们的CLA的repo中这样做一次。

本项目已采用Microsoft开源行为准则。有关更多信息，请参阅行为准则FAQ或通过[email protected]联系以获取任何额外的问题或评论。