快速入门：Azure Key Vault用于.NET的机密客户端库

开始使用适用于.NET的Azure Key Vault秘密客户端库。 Azure Key Vault是一种云服务，为机密提供安全存储。可以安全地存储密钥、密码、证书和其他机密。可以通过Azure门户创建和管理Azure密钥保管库。本快速入门介绍如何使用 .NET 客户端库从Azure密钥保管库创建、检索和删除机密

Key Vault客户端库资源：

API 参考文档 | 库源代码 | 软件包

有关Key Vault和机密的详细信息，请参阅：

Key Vault 概述
机密概述。

先决条件

Azure订阅 - 免费创建一个订阅
.NET 6 SDK 或更高版本
Azure CLI 或 Azure PowerShell
密钥保管库 - 可以使用 Azure portal、Azure CLI 或 Azure PowerShell 创建一个

本快速入门使用 dotnet 和 Azure CLI 或 Azure PowerShell。

本快速入门使用Azure身份库和Azure CLI对用户进行身份验证，以便访问Azure服务。开发人员还可以使用Visual Studio或Visual Studio Code对其调用进行身份验证，有关详细信息，请参阅使用 Azure标识客户端库对客户端进行身份验证。

运行 az login 命令。
```
az login
```
如果 CLI 可以打开默认浏览器，它将执行此操作并加载Azure登录页。

否则，请在 https://aka.ms/deviceloginchina 处打开浏览器页，然后输入终端中显示的授权代码。
在浏览器中使用帐户凭据登录。

授予对 Key Vault 的访问权限

若要通过 Role-Based Access Control （RBAC）获取密钥保管库的权限，请使用 Azure CLI 命令az 角色分配创建为“用户主体名称”（UPN）分配角色。

az role assignment create --role "Key Vault Secrets Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

将 <upn>、<subscription-id>、<resource-group-name> 和 <your-unique-keyvault-name> 替换为你的实际值。你的 UPN 通常采用电子邮件地址格式（例如 username@domain.com）。

本快速入门使用 Azure 身份库和 Azure PowerShell 对用户进行身份验证，以使用 Azure 服务。开发人员还可以使用Visual Studio或Visual Studio Code对其调用进行身份验证，有关详细信息，请参阅使用 Azure标识客户端库对客户端进行身份验证。

运行 Connect-AzAccount -Environment AzureChinaCloud 命令。
```
Connect-AzAccount -Environment AzureChinaCloud
```
如果 PowerShell 可以打开默认浏览器，它将执行此操作并加载Azure登录页。

否则，请在 https://aka.ms/deviceloginchina 处打开浏览器页，然后输入终端中显示的授权代码。
在浏览器中使用帐户凭据登录。

授予对 Key Vault 的访问权限

若要通过 Role-Based Access Control （RBAC）0 获取密钥保管库的权限，请使用 Azure PowerShell cmdlet New-AzRoleAssignment 为“用户主体名称”（UPN）分配角色。

New-AzRoleAssignment -SignInName "<upn>" -RoleDefinitionName "Key Vault Secrets Officer" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

将 <upn>、<subscription-id>、<resource-group-name> 和 <your-unique-keyvault-name> 替换为你的实际值。你的 UPN 通常采用电子邮件地址格式（例如 username@domain.com）。

创建新的.NET控制台应用

在命令外壳中，运行以下命令以创建名为 key-vault-console-app 的项目：
```
dotnet new console --name key-vault-console-app
```
切换到新创建的 key-vault-console-app 目录，然后运行以下命令来生成项目：
```
dotnet build
```
生成输出不应包含警告或错误。
```
Build succeeded.
 0 Warning(s)
 0 Error(s)
```

安装这些软件包

在命令行界面中，安装用于.NET的Azure Key Vault机密客户端库：

dotnet add package Azure.Security.KeyVault.Secrets

对于本快速入门，还需要安装Azure标识客户端库：

dotnet add package Azure.Identity

设置环境变量

此应用程序使用 Key Vault 名称作为名为 KEY_VAULT_NAME 的环境变量。

Windows

set KEY_VAULT_NAME=<vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<vault-name>"

macOS 或 Linux

export KEY_VAULT_NAME=<vault-name>

对象模型

.NET的 Azure Key Vault 机密客户端库允许管理机密。代码示例部分介绍如何创建客户端以及设置、检索和删除密码。

代码示例

添加指令

在 Program.cs 的顶部添加以下指令：

// <directives>
using System;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
// </directives>

namespace key_vault_console_app
{
    class Program
    {
        static void Main(string[] args)
        {
            bool isSoftDeleteEnabled = true;
            string secretName = "mySecret";

            // <authenticate>
            string keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
            var kvUri = "https://" + keyVaultName + ".vault.azure.cn";

            var client = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());
            // </authenticate>

            Console.Write("Input the value of your secret > ");
            string secretValue = Console.ReadLine();

            Console.Write("Creating a secret in " + keyVaultName + " called '" + secretName + "' with the value '" + secretValue + "` ...");

            // <setsecret>
            client.SetSecret(secretName, secretValue);
            // </setsecret>

            Console.WriteLine(" done.");

            Console.WriteLine("Forgetting your secret.");
            secretValue = "";
            Console.WriteLine("Your secret is '" + secretValue + "'.");

            Console.WriteLine("Retrieving your secret from " + keyVaultName + ".");

            // <getsecret>
            KeyVaultSecret secret = client.GetSecret(secretName);
            // </getsecret>

            Console.WriteLine("Your secret is '" + secret.Value + "'.");

            Console.Write("Deleting your secret from " + keyVaultName + " ...");

            // <deletesecret>
            client.StartDeleteSecret(secretName);
            // </deletesecret>

            if (!isSoftDeleteEnabled)
            {
                System.Threading.Thread.Sleep(5000);
                Console.WriteLine(" done.");

                return;
            }

            System.Threading.Thread.Sleep(60000);
            Console.WriteLine(" done.");

            Console.Write("Purging your secret from " + keyVaultName + " ...");

            // <purgesecret>
            client.PurgeDeletedSecret(secretName);
            // </purgesecret>

            System.Threading.Thread.Sleep(5000);
            Console.WriteLine(" done.");
        }
    }
}

进行身份验证并创建客户端

对大多数Azure服务的应用程序请求必须获得授权。建议在代码中使用由 Azure Identity 客户端库提供的 DefaultAzureCredential 类来实现与 Azure 服务的无密码连接。 DefaultAzureCredential 支持多种身份验证方法，并确定应在运行时使用哪种方法。通过这种方法，你的应用可在不同环境（本地与生产）中使用不同的身份验证方法，而无需实现特定于环境的代码。

在本快速入门中，DefaultAzureCredential使用登录到Azure CLI的本地开发用户的凭据向密钥保管库进行身份验证。将应用程序部署到Azure时，同一DefaultAzureCredential代码可以自动发现和使用分配给应用服务、虚拟机或其他服务的托管标识。有关详细信息，请参阅托管标识概述。

在此示例中，密钥保管库的名称扩展为密钥保管库 URI，格式为 https://<your-key-vault-name>.vault.azure.cn。有关向密钥保管库进行身份验证的详细信息，请参阅开发人员指南。

// <directives>
using System;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
// </directives>

namespace key_vault_console_app
{
    class Program
    {
        static void Main(string[] args)
        {
            bool isSoftDeleteEnabled = true;
            string secretName = "mySecret";

            // <authenticate>
            string keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
            var kvUri = "https://" + keyVaultName + ".vault.azure.cn";

            var client = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());
            // </authenticate>

            Console.Write("Input the value of your secret > ");
            string secretValue = Console.ReadLine();

            Console.Write("Creating a secret in " + keyVaultName + " called '" + secretName + "' with the value '" + secretValue + "` ...");

            // <setsecret>
            client.SetSecret(secretName, secretValue);
            // </setsecret>

            Console.WriteLine(" done.");

            Console.WriteLine("Forgetting your secret.");
            secretValue = "";
            Console.WriteLine("Your secret is '" + secretValue + "'.");

            Console.WriteLine("Retrieving your secret from " + keyVaultName + ".");

            // <getsecret>
            KeyVaultSecret secret = client.GetSecret(secretName);
            // </getsecret>

            Console.WriteLine("Your secret is '" + secret.Value + "'.");

            Console.Write("Deleting your secret from " + keyVaultName + " ...");

            // <deletesecret>
            client.StartDeleteSecret(secretName);
            // </deletesecret>

            if (!isSoftDeleteEnabled)
            {
                System.Threading.Thread.Sleep(5000);
                Console.WriteLine(" done.");

                return;
            }

            System.Threading.Thread.Sleep(60000);
            Console.WriteLine(" done.");

            Console.Write("Purging your secret from " + keyVaultName + " ...");

            // <purgesecret>
            client.PurgeDeletedSecret(secretName);
            // </purgesecret>

            System.Threading.Thread.Sleep(5000);
            Console.WriteLine(" done.");
        }
    }
}

保存机密

控制台应用已通过身份验证，接下来将密码添加到 Key Vault 中。对于此任务，请使用 SetSecretAsync 方法。

该方法的第一个参数接受机密的名称。在此示例中，变量 secretName 存储字符串“mySecret”。

该方法的第二个参数接受机密信息的值。在此示例中，机密由用户通过命令行输入，并存储在变量 secretValue 中。

await client.SetSecretAsync(secretName, secretValue);

注意

如果机密名已存在，则该代码将创建该机密的新版本。

检索机密

现在，可以使用 GetSecretAsync 方法检索以前设置的值。

var secret = await client.GetSecretAsync(secretName);

机密现已保存为 secret.Value。

删除机密

最后，使用 StartDeleteSecretAsync 和 PurgeDeletedSecretAsync 方法从 Key Vault 中删除机密。

var operation = await client.StartDeleteSecretAsync(secretName);
// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();

await client.PurgeDeletedSecretAsync(secretName);

示例代码

通过完成以下步骤，修改.NET控制台应用以与Key Vault交互：

将 Program.cs 中的代码替换为以下代码：

using System;
using System.Threading.Tasks;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

namespace key_vault_console_app
{
    class Program
    {
        static async Task Main(string[] args)
        {
            const string secretName = "mySecret";
            var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
            var kvUri = $"https://{keyVaultName}.vault.azure.cn";

            var client = new SecretClient(new Uri(kvUri), new DefaultAzureCredential());

            Console.Write("Input the value of your secret > ");
            var secretValue = Console.ReadLine();

            Console.Write($"Creating a secret in {keyVaultName} called '{secretName}' with the value '{secretValue}' ...");
            await client.SetSecretAsync(secretName, secretValue);
            Console.WriteLine(" done.");

            Console.WriteLine("Forgetting your secret.");
            secretValue = string.Empty;
            Console.WriteLine($"Your secret is '{secretValue}'.");

            Console.WriteLine($"Retrieving your secret from {keyVaultName}.");
            var secret = await client.GetSecretAsync(secretName);
            Console.WriteLine($"Your secret is '{secret.Value.Value}'.");

            Console.Write($"Deleting your secret from {keyVaultName} ...");
            DeleteSecretOperation operation = await client.StartDeleteSecretAsync(secretName);
            // You only need to wait for completion if you want to purge or recover the secret.
            await operation.WaitForCompletionAsync();
            Console.WriteLine(" done.");

            Console.Write($"Purging your secret from {keyVaultName} ...");
            await client.PurgeDeletedSecretAsync(secretName);
            Console.WriteLine(" done.");
        }
    }
}

测试和验证

执行以下命令来运行应用。
```
dotnet run
```
出现提示时，输入一个密码值。例如，mySecretPassword。

以下输出的一个变体将会出现：

Input the value of your secret > mySecretPassword
Creating a secret in <vault-name> called 'mySecret' with the value 'mySecretPassword' ... done.
Forgetting your secret.
Your secret is ''.
Retrieving your secret from <vault-name>.
Your secret is 'mySecretPassword'.
Deleting your secret from <vault-name> ... done.    
Purging your secret from <vault-name> ... done.

后续步骤

若要详细了解Key Vault以及如何将其与应用集成，请参阅以下文章：

查看 Azure Key Vault 概述
请参阅应用服务应用程序教程中的 Access Key Vault
查看虚拟机教程中的 Access Key Vault
请参阅 Azure Key Vault 开发人员指南
查看 Key Vault 安全概述
查看特定于机密的安全最佳做法

Last updated on 2026-04-22

共用方式為

快速入门：Azure Key Vault用于.NET的机密客户端库

先决条件

设置

登录到 Azure

授予对 Key Vault 的访问权限

创建新的.NET控制台应用

安装这些软件包

设置环境变量

对象模型

代码示例

添加指令

进行身份验证并创建客户端

保存机密

检索机密

删除机密

示例代码

测试和验证

后续步骤

其他資源