Azure 密钥保管库入门Get started with Azure Key Vault

本文有助于使用 PowerShell 完成 Azure Key Vault 入门,并详细介绍如何完成以下活动:This article helps you get started with Azure Key Vault using PowerShell and walks you through the following activities:

  • 如何在 Azure 中创建强化容器(保管库)。How to create a hardened container (a vault) in Azure.
  • 如何使用 KeyVault 在 Azure 中存储和管理加密密钥和机密。How to use KeyVault to store and manage cryptographic keys and secrets in Azure.
  • 应用程序如何使用该密钥或密码。How an application can use that key or password.

大多数区域都提供了 Azure 密钥保管库。Azure Key Vault is available in most regions. 有关详细信息,请参阅 密钥保管库定价页For more information, see the Key Vault pricing page.

有关跨平台命令行接口说明,请参阅此对应教程For Cross-Platform Command-Line Interface instructions, see this equivalent tutorial.

要求Requirements

在继续之前,请确认你具有:Before continuing, confirm that you have:

  • 一个 Azure 订阅An Azure subscription. 如果没有订阅,可以注册一个试用帐户If you do not have one, you can sign up for a trial account.
  • Azure PowerShell最低版本为 1.1.0Azure PowerShell, minimum version of 1.1.0. 要安装 Azure PowerShell 并将其与 Azure 订阅相关联,请参阅如何安装和配置 Azure PowerShellTo install Azure PowerShell and associate it with your Azure subscription, see How to install and configure Azure PowerShell. 如果已安装了 Azure PowerShell,但不知道版本,请在 Azure PowerShell 控制台中键入 (Get-Module azure -ListAvailable).VersionIf you have already installed Azure PowerShell and do not know the version, from the Azure PowerShell console, type (Get-Module azure -ListAvailable).Version. 如果已安装 Azure PowerShell 版本 0.9.1 到 0.9.8,仍可以使用本教程,但需要进行一些细微更改。When you have Azure PowerShell version 0.9.1 through 0.9.8 installed, you can still use this tutorial with some minor changes. 例如,必须使用 Switch-AzureMode AzureResourceManager 命令,并且某些 Azure 密钥保管库命令已更改。For example, you must use the Switch-AzureMode AzureResourceManager command and some of the Azure Key Vault commands have changed. 有关版本 0.9.1 到 0.9.8 的 Key Vault cmdlet 的列表,请参阅 Azure Key Vault CmdletFor a list of the Key Vault cmdlets for versions 0.9.1 through 0.9.8, see Azure Key Vault Cmdlets.
  • 一个可以配置为使用 Key Vault 的应用程序An application that can be configured to use Key Vault. 可以从 Microsoft 下载中心获取示例应用程序。A sample application is available from the Microsoft Download Center. 有关说明,请参阅随附的自述文件。For instructions, see the accompanying Readme file.

Note

本文假定读者对 PowerShell 和 Azure 有一个基本的了解。This article assumes a basic understanding of PowerShell and Azure. 有关 PowerShell 的详细信息,请参阅 Windows PowerShell 入门For more information on PowerShell, see Getting started with Windows PowerShell.

要获取你在本教程中看到的任何 cmdlet 的详细帮助,请使用 Get-Help cmdlet。To get detailed help for any cmdlet that you see in this tutorial, use the Get-Help cmdlet.

Get-Help <cmdlet-name> -Detailed

例如,若要获取有关 Connect-AzureRmAccount cmdlet 的帮助,请键入:For example, to get help for the Connect-AzureRmAccount cmdlet, type:

Get-Help Connect-AzureRmAccount -Detailed

还可阅读以下文章,熟悉 Azure PowerShell 中的 Azure 资源管理器部署模型:You can also read the following articles to get familiar with Azure Resource Manager deployment model in Azure PowerShell:

连接到订阅Connect to your subscriptions

启动 Azure PowerShell 会话,并使用以下命令登录用户的 Azure 帐户:Start an Azure PowerShell session and sign in to your Azure account with the following command:

Connect-AzureRmAccount -Environment AzureChinaCloud

在弹出的浏览器窗口中,输入 Azure 帐户用户名和密码。In the pop-up browser window, enter your Azure account user name and password. Azure PowerShell 会获取与此帐户关联的所有订阅,并按默认使用第一个订阅。Azure PowerShell gets all the subscriptions that are associated with this account and by default, uses the first one.

如果有多个订阅,并想要指定其中一个订阅供 Azure 密钥保管库使用,请键入以下内容以查看帐户的订阅:If you have multiple subscriptions and want to specify a specific one to use for Azure Key Vault, type the following to see the subscriptions for your account:

Get-AzureRmSubscription

然后,如果要指定要使用的订阅,请键入:Then, to specify the subscription to use, type:

Set-AzureRmContext -SubscriptionId <subscription ID>

有关配置 Azure PowerShell 的详细信息,请参阅 如何安装和配置 Azure PowerShellFor more information about configuring Azure PowerShell, see How to install and configure Azure PowerShell.

创建新的资源组Create a new resource group

使用 Azure Resource Manager 时,会在资源组中创建所有相关资源。When you use Azure Resource Manager, all related resources are created inside a resource group. 在本教程中,我们创建名为 ContosoResourceGroup 的新资源组:We will create a new resource group named ContosoResourceGroup for this tutorial:

New-AzureRmResourceGroup -Name 'ContosoResourceGroup' -Location 'China North'

创建密钥保管库Create a key vault

使用 New-AzureRmKeyVault cmdlet 创建密钥保管库。Use the New-AzureRmKeyVault cmdlet to create a key vault. 此 cmdlet 包含三个必需参数:资源组名称、密钥保管库名称和地理位置 。This cmdlet has three mandatory parameters: a resource group name, a key vault name, and the geographic location.

例如,如果使用:For example, if you use:

  • 保管库名称 ContosoKeyVaultVault name of ContosoKeyVault.
  • 资源组名称 ContosoResourceGroupResource group name of ContosoResourceGroup.
  • 位置“中国北部”。 The location of China North.

需键入:you would type:

New-AzureRmKeyVault -VaultName 'ContosoKeyVault' -ResourceGroupName 'ContosoResourceGroup' -Location 'China North'

Key Vault 创建命令完成后的输出

此 cmdlet 的输出显示创建的密钥保管库的属性。The output of this cmdlet shows properties of the key vault that you created. 两个最重要的属性是:The two most important properties are:

  • 保管库名称:在本示例中,此项为 ContosoKeyVaultVault Name: In the example, this is ContosoKeyVault. 将在其他密钥保管库 cmdlet 中使用此名称。You will use this name for other Key Vault cmdlets.
  • 保管库 URI:在本示例中为 https://contosokeyvault.vault.azure.cn/.inVault URI: https://contosokeyvault.vault.azure.cn/.in the example. 通过其 REST API 使用保管库的应用程序必须使用此 URI。Applications that use your vault through its REST API must use this URI.

Azure 帐户现已获取在此密钥保管库上执行任何作业的授权。Your Azure account is now authorized to perform any operations on this key vault. 而且没有其他人有此授权。As yet, nobody else is.

Note

在尝试创建新的密钥保管库时,可能会看到错误“该订阅未注册为使用命名空间‘Microsoft.KeyVault’” 。When you try to create your new key vault you may see the error The subscription is not registered to use namespace 'Microsoft.KeyVault'. 如果显示该消息,请运行 Register-AzureRmResourceProvider -ProviderNamespace "Microsoft.KeyVault"If that message appears run Register-AzureRmResourceProvider -ProviderNamespace "Microsoft.KeyVault". 成功完成注册以后,可重新运行 New-AzureRmKeyVault 命令。After the registration successfully completes, you can rerun the New-AzureRmKeyVault command. 有关详细信息,请参阅 Register-AzureRmResourceProviderFor more information, see Register-AzureRmResourceProvider.

将密钥或机密添加到保管库Add a key or secret to the key vault

可能需要以多种不同的方式与 Key Vault 以及密钥或机密交互。There are a couple of different ways that you may need to interact with Key Vault and keys or secrets.

Azure Key Vault 生成软件保护密钥Azure Key Vault generates a software protected key

如果希望 Azure Key Vault 创建一个软件保护密钥,请使用 Add-AzureKeyVaultKey cmdlet,并键入:If you want Azure Key Vault to create a software-protected key for you, use the Add-AzureKeyVaultKey cmdlet, and type:

$key = Add-AzureKeyVaultKey -VaultName 'ContosoKeyVault' -Name 'ContosoFirstKey' -Destination 'Software'

若要查看此密钥的 URI,请键入:to view the URI for this key type:

$key.id

可以通过密钥的 URI 引用已创建或上传到 Azure Key Vault 的密钥。You can reference a key that you created or uploaded to Azure Key Vault by using its URI. 若要获取当前版本,可以使用 https://ContosoKeyVault.vault.azure.cn/keys/ContosoFirstKey ,使用 https://ContosoKeyVault.vault.azure.cn/keys/ContosoFirstKey/cgacf4f763ar42ffb0a1gca546aygd87 可获取此特定版本。To get the current version you can use https://ContosoKeyVault.vault.azure.cn/keys/ContosoFirstKey and use https://ContosoKeyVault.vault.azure.cn/keys/ContosoFirstKey/cgacf4f763ar42ffb0a1gca546aygd87 to get this specific version.

将现有的 PFX 文件导入 Azure Key VaultImporting an existing PFX file into Azure Key Vault

如果现有的密钥存储在 pfx 文件中,而该文件需上传到 Azure Key Vault,则执行不同的步骤。If existing keys are stored in a pfx file that you want to upload to Azure Key Vault, the steps are different. 例如:For example:

  • 如果在 .PFX 文件中已经有一个软件保护密钥If you have an existing software-protected key in a .PFX file
  • 该 pfx 文件名为 softkey.pfxThe pfx file is named softkey.pfx
  • 该文件存储在 C 驱动器中。The file is stored in the C drive.

可键入:You can type:

$securepfxpwd = ConvertTo-SecureString –String '123' –AsPlainText –Force  // This stores the password 123 in the variable $securepfxpwd

然后键入以下内容以从 .PFX 文件导入密钥,这样,便会使用密钥保管库服务中的软件来保护密钥:Then type the following to import the key from the .PFX file, which protects the key by software in the Key Vault service:

$key = Add-AzureKeyVaultKey -VaultName 'ContosoKeyVault' -Name 'ContosoImportedPFX' -KeyFilePath 'c:\softkey.pfx' -KeyFilePassword $securepfxpwd

若要显示此密钥的 URI,请键入:To display the URI for this key, type:

$Key.id

若要查看密钥,请键入:To view your key, type:

Get-AzureKeyVaultKey –VaultName 'ContosoKeyVault'

若要在门户中查看 PFX 文件的属性,则会看到类似于下图所示的内容。If you want to view the properties of the PFX file in the portal, you will see something similar to the image shown below.

证书在门户中的显示效果

向 Azure Key Vault 添加机密To add a secret to Azure Key Vault

若要将名为 SQLPassword 且其 Azure 密钥保管库的值为 Pa$$w0rd 的机密(属于密码)添加到保管库,请先键入以下内容,将 Pa$$w0rd 的值转换成安全字符串:To add a secret to the vault, which is a password named SQLPassword and has the value of Pa$$w0rd to Azure Key Vault, first convert the value of Pa$$w0rd to a secure string by typing:

$secretvalue = ConvertTo-SecureString 'Pa$$w0rd' -AsPlainText -Force

然后,键入:Then, type:

$secret = Set-AzureKeyVaultSecret -VaultName 'ContosoKeyVault' -Name 'SQLPassword' -SecretValue $secretvalue

现在,可以通过使用密码的 URI,引用已添加到 Azure 密钥保管库的此密码。You can now reference this password that you added to Azure Key Vault, by using its URI. 使用 https://ContosoVault.vault.azure.cn/secrets/SQLPassword 始终可获取当前版本,而使用 https://ContosoVault.vault.azure.cn/secrets/SQLPassword/90018dbb96a84117a0d2847ef8e7189d 可获取此特定版本。Use https://ContosoVault.vault.azure.cn/secrets/SQLPassword to always get the current version, and use https://ContosoVault.vault.azure.cn/secrets/SQLPassword/90018dbb96a84117a0d2847ef8e7189d to get this specific version.

若要显示此机密的 URI,请键入:To display the URI for this secret, type:

$secret.Id

若要查看密码,请键入:Get-AzureKeyVaultSecret –VaultName 'ContosoKeyVault'。也可在门户中查看该机密。To view your secret, type: Get-AzureKeyVaultSecret –VaultName 'ContosoKeyVault' Or alternatively you may view the secret on the portal.

secret

若要查看机密中包含的纯文本形式的值,请执行以下命令:To view the value contained in the secret as plain text:

(get-azurekeyvaultsecret -vaultName "Contosokeyvault" -name "SQLPassword").SecretValueText

现在,可以在应用程序中使用该密钥保管库以及密钥或机密。Now, your key vault and key or secret are ready for applications to use. 现在可以授权应用程序使用这些信息。Now you authorize applications to use them.

将应用程序注册到 Azure Active DirectoryRegister an application with Azure Active Directory

此步骤通常由开发人员在独立的计算机上完成。This step would usually be done by a developer, on a separate computer. 它不是特定于 Azure Key Vault 的。It is not specific to Azure Key Vault. 如需将应用程序注册到 Azure Active Directory 的详细步骤,则应参阅将应用程序与 Azure Active Directory 集成一文或使用门户创建可访问资源的 Azure Active Directory 应用程序和服务主体一文For detailed steps on registering an application with Azure Active Directory you should review the article titled Integrating applications with Azure Active Directory or Use portal to create an Azure Active Directory application and service principal that can access resources

Important

要完成本教程,你的帐户、保管库以及要在本步骤中注册的应用程序全都必须位于相同的 Azure 目录中。To complete the tutorial, your account, the vault, and the application that you will register in this step must all be in the same Azure directory.

使用密钥保管库的应用程序必须使用 Azure Active Directory 的令牌进行身份验证。Applications that use a key vault must authenticate by using a token from Azure Active Directory. 应用程序的所有者首先必须在其 Azure Active Directory 中注册该应用程序。The owner of the application must first register the application in their Azure Active Directory. 注册结束后,应用程序所有者获得以下值:At the end of registration, the application owner gets the following values:

  • 应用程序 IDAn Application ID
  • 身份验证密钥(也称共享机密)。An authentication key (also known as the shared secret).

应用程序必须向 Azure Active Directory 提供这两个值才能获取令牌。The application must present both these values to Azure Active Directory, to get a token. 应用程序配置取决于应用程序。The application configuration depends on the application. 对于 Key Vault 示例应用程序,应用程序所有者会在 app.config 文件中设置这些值。For the Key Vault sample application, the application owner sets these values in the app.config file.

要在 Azure Active Directory 中注册应用程序,请执行以下操作:To register the application in Azure Active Directory:

  1. 登录到 Azure 门户Sign in to the Azure portal.

  2. 在左侧单击“应用注册” 。On the left, click App registrations. 如果没有看到应用注册,请单击“更多服务” 。If you don't see app registrations, click on more services.

    Note

    必须选择包含用于创建 Key Vault 的 Azure 订阅的相同目录。You must select the same directory that contains the Azure subscription with which you created your key vault.

  3. 单击“新建应用程序注册” 。Click New application registration.

  4. 在“创建” 边栏选项卡上提供应用程序的名称,然后选择“WEB 应用程序和/或 WEB API” (默认值)并指定 Web 应用程序的“登录 URL”。 On the Create blade provide a name for your application, and then select WEB APPLICATION AND/OR WEB API (the default) and specify the SIGN-ON URL for your web application. 对于此步骤,如果目前没有该信息,可以进行编造(例如,可以指定 https://test1.contoso.com )。If you don't have this information at this time, you can make it up for this step (for example, you could specify https://test1.contoso.com ). 是否存在这些站点并不重要。It does not matter if these sites exist.

    新建应用程序注册

    Warning

    请确保选择“WEB 应用程序和/或 WEB API”,否则在设置下看不到“密钥”选项。 Make sure that you chose WEB APPLICATION AND/OR WEB API if you did not you will not see the keys option under settings.

  5. 单击“创建” 按钮。Click the Create button.

  6. 完成应用注册以后,可看到已注册应用的列表。When the app registration is completed, you will see the list of registered apps. 找到注册的应用,然后单击它。Find the app that you registered and click on it.

  7. 单击“已注册应用”边栏选项卡,然后复制应用程序 ID Click on the Registered app blade copy the Application ID

  8. 单击“所有设置” Click on All settings

  9. 在“设置”边栏选项卡上,单击“密钥” On the Settings blade click on keys

  10. 在“密钥说明”框中键入说明,选择持续时间,然后单击“保存”。Type in a description in the Key description box and select a duration, and then click SAVE. 页面会刷新,随后显示密钥值。The page refreshes and now shows a key value.

  11. 在下一步,需使用“应用程序 ID”和“密钥”信息来设置保管库的权限。 You will use the Application ID and the Key information in the next step to set permissions on your vault.

授权应用程序使用密钥或机密Authorize the application to use the key or secret

可以通过两种方式授权应用程序访问保管库中的密钥或机密。There are two ways to authorize the application to access the key or secret in the vault.

使用 PowerShellUsing PowerShell

若要使用 PowerShell,可使用 Set-AzureRmKeyVaultAccessPolicy cmdlet。To use PowerShell, use the Set-AzureRmKeyVaultAccessPolicy cmdlet.

例如,如果保管库名称是 ContosoKeyVault ,要授权的应用程序的客户端 ID 为 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed,而你希望授权应用程序使用保管库中的密钥来进行解密和签名,请运行以下 cmdlet:For example, if your vault name is ContosoKeyVault and the application you want to authorize has a client ID of 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed, and you want to authorize the application to decrypt and sign with keys in your vault, run the following cmdlet:

Set-AzureRmKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -ServicePrincipalName 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed -PermissionsToKeys decrypt,sign

如果要授权同一应用程序读取保管库中的机密,请运行以下命令:If you want to authorize that same application to read secrets in your vault, run the following:

Set-AzureRmKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -ServicePrincipalName 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed -PermissionsToSecrets Get

使用 Azure 门户Using the Azure portal

若要更改应用程序的授权以使用密钥或机密,请执行以下操作:To change the authorization of an application to use keys or secrets:

  1. 从 Key Vault 资源边栏选项卡中选择“访问策略” Select Access Policies from the Key Vault resource blade
  2. 单击边栏选项卡顶部的 [+ 新增] 按钮Click the [+ Add new] button at the top of the blade
  3. 单击“选择主体” 以选择前面创建的应用程序Click Select Principal to select the application you created earlier
  4. 从“密钥权限” 下拉列表中选择“解密”和“签名”,以授权应用程序使用保管库中的密钥进行解密和签名From the Key permissions drop down, select "Decrypt" and "Sign" to authorize the application to decrypt and sign with keys in your vault
  5. 从“机密权限” 下拉列表中选择“获取”,以允许应用程序读取保管库中的机密From the Secret permissions drop-down, select "Get" to allow the application to read secrets in the vault

删除密钥保管库以及关联的密钥和机密Delete the key vault and associated keys and secrets

如果不再需要密钥保管库及其包含的密钥或机密,可以使用 Remove-AzureRmKeyVault cmdlet 来删除密钥保管库:If you no longer need the key vault and the key or secret that it contains, you can delete the key vault by using the Remove-AzureRmKeyVault cmdlet:

Remove-AzureRmKeyVault -VaultName 'ContosoKeyVault'

或者,可以删除整个 Azure 资源组,其中包括密钥保管库和你加入该组的任何其他资源:Or, you can delete an entire Azure resource group, which includes the key vault and any other resources that you included in that group:

Remove-AzureRmResourceGroup -ResourceGroupName 'ContosoResourceGroup'

其他 Azure PowerShell CmdletOther Azure PowerShell Cmdlets

可能会发现有助于管理 Azure 密钥保管库的其他命令:Other commands that you might find useful for managing Azure Key Vault:

  • $Keys = Get-AzureKeyVaultKey -VaultName 'ContosoKeyVault':此命令获取以表格形式显示的所有密钥和所选属性。$Keys = Get-AzureKeyVaultKey -VaultName 'ContosoKeyVault': This command gets a tabular display of all keys and selected properties.
  • $Keys[0]:此命令显示特定密钥的完整属性列表$Keys[0]: This command displays a full list of properties for the specified key
  • Get-AzureKeyVaultSecret:此命令列出以表格形式显示的所有机密名称和所选属性。Get-AzureKeyVaultSecret: This command lists a tabular display of all secret names and selected properties.
  • Remove-AzureKeyVaultKey -VaultName 'ContosoKeyVault' -Name 'ContosoFirstKey':示范如何删除特定密钥。Remove-AzureKeyVaultKey -VaultName 'ContosoKeyVault' -Name 'ContosoFirstKey': Example how to remove a specific key.
  • Remove-AzureKeyVaultSecret -VaultName 'ContosoKeyVault' -Name 'SQLPassword':示范如何删除特定机密。Remove-AzureKeyVaultSecret -VaultName 'ContosoKeyVault' -Name 'SQLPassword': Example how to remove a specific secret.

后续步骤Next steps