使用 PowerShell 管理 Azure Stack Hub 中的 Key VaultManage Key Vault in Azure Stack Hub using PowerShell

本文介绍如何使用 PowerShell 在 Azure Stack Hub 中创建和管理密钥保管库。This article describes how to create and manage a key vault in Azure Stack Hub using PowerShell. 了解如何使用 Key Vault PowerShell cmdlet 执行以下操作:You'll learn how to use Key Vault PowerShell cmdlets to:

  • 创建密钥保管库。Create a key vault.
  • 存储和管理加密密钥和机密。Store and manage cryptographic keys and secrets.
  • 授权用户或应用调用保管库中的操作。Authorize users or apps to invoke operations in the vault.

备注

本文中介绍的 Key Vault PowerShell cmdlet 在 Azure PowerShell SDK 中提供。The Key Vault PowerShell cmdlets described in this article are provided in the Azure PowerShell SDK.

先决条件Prerequisites

启用适用于 Key Vault 操作的租户订阅Enable your tenant subscription for Key Vault operations

在对某个密钥保管库发出任何操作之前,必须确保租户订阅可以进行保管库操作。Before you can issue any operations against a key vault, you must ensure that your tenant subscription is enabled for vault operations. 若要验证密钥保管库操作是否已启用,请运行以下命令:To verify that key vault operations are enabled, run the following command:

Get-AzureRmResourceProvider -ProviderNamespace Microsoft.KeyVault | ft -Autosize

如果订阅可以进行保管库操作,则输出会显示某个密钥保管库的所有资源类型的“RegistrationState”**** 为“已注册”****。If your subscription is enabled for vault operations, the output shows RegistrationState is Registered for all resource types of a key vault.

Powershell 中的密钥保管库注册状态

如果未启用保管库操作,请发出以下命令,以便在订阅中注册 Key Vault 服务:If vault operations are not enabled, issue the following command to register the Key Vault service in your subscription:

Register-AzureRmResourceProvider -ProviderNamespace Microsoft.KeyVault

如果注册成功,则返回以下输出:If the registration is successful, the following output is returned:

在 Powershell 中注册密钥保管库成功

调用密钥保管库命令时,可能会遇到错误,例如“该订阅未注册为使用命名空间 'Microsoft.KeyVault'”。如果遇到错误,请确认已按照前面的说明启用 Key Vault 资源提供程序。When you invoke the key vault commands, you might receive an error, such as "The subscription is not registered to use namespace 'Microsoft.KeyVault'." If you get an error, confirm you've enabled the Key Vault resource provider by following the previous instructions.

创建密钥保管库Create a key vault

在创建密钥保管库之前,请创建资源组,使得与密钥保管库相关的所有资源都存在于一个资源组中。Before you create a key vault, create a resource group so that all of the resources related to the key vault exist in a resource group. 使用以下命令来创建新资源组:Use the following command to create a new resource group:

New-AzureRmResourceGroup -Name "VaultRG" -Location local -verbose -Force

在 Powershell 中生成的新资源组

现在,请使用 New-AzureRMKeyVault cmdlet 在以前创建的资源组中创建一个密钥保管库。Now, use the New-AzureRMKeyVault cmdlet to create a key vault in the resource group that you created earlier. 此命令读取三个必需参数:资源组名称、密钥保管库名称和地理位置。This command reads three mandatory parameters: resource group name, key vault name, and geographic location.

运行以下命令,创建密钥保管库:Run the following command to create a key vault:

New-AzureRmKeyVault -VaultName "Vault01" -ResourceGroupName "VaultRG" -Location local -verbose

在 Powershell 中生成的新密钥保管库

此命令的输出会显示创建的密钥保管库的属性。The output of this command shows the properties of the key vault that you created. 当应用访问此保管库时,它必须使用“保管库 URI”**** 属性(在本例中为 https://vault01.vault.local.azurestack.external)。When an app accesses this vault, it must use the Vault URI property, which is https://vault01.vault.local.azurestack.external in this example.

Active Directory 联合身份验证服务 (AD FS) 部署Active Directory Federation Services (AD FS) deployment

在 AD FS 部署中,可能会收到此警告:“未设置访问策略。In an AD FS deployment, you might get this warning: "Access policy is not set. 没有用户或应用程序具有使用此保管库所需的访问权限。”No user or application has access permission to use this vault." 若要解决此问题,请通过 Set-AzureRmKeyVaultAccessPolicy 命令设置保管库的访问策略:To resolve this issue, set an access policy for the vault by using the Set-AzureRmKeyVaultAccessPolicy command:

# Obtain the security identifier(SID) of the active directory user
$adUser = Get-ADUser -Filter "Name -eq '{Active directory user name}'"
$objectSID = $adUser.SID.Value

# Set the key vault access policy
Set-AzureRmKeyVaultAccessPolicy -VaultName "{key vault name}" -ResourceGroupName "{resource group name}" -ObjectId "{object SID}" -PermissionsToKeys {permissionsToKeys} -PermissionsToSecrets {permissionsToSecrets} -BypassObjectIdValidation

管理密钥和机密Manage keys and secrets

创建保管库后,使用以下步骤来创建并管理保管库中的密钥和机密。After you create a vault, use these steps to create and manage keys and secrets in the vault.

创建密钥Create a key

使用 Add-AzureKeyVaultKey cmdlet 在密钥保管库中创建或导入受软件保护的密钥:Use the Add-AzureKeyVaultKey cmdlet to create or import a software-protected key in a key vault:

Add-AzureKeyVaultKey -VaultName "Vault01" -Name "Key01" -verbose -Destination Software

可以使用 -Destination 参数来指出密钥是受软件保护的。The -Destination parameter is used to specify that the key is software protected. 成功创建密钥后,此命令会输出已创建密钥的详细信息。When the key is successfully created, the command outputs the details of the created key.

在 Powershell 中生成的新密钥保管库密钥

现在可以通过已创建密钥的 URI 来引用该密钥。You can now reference the created key by using its URI. 如果创建或导入的密钥的名称与现有密钥相同,则会使用新密钥中指定的值来更新原始密钥。If you create or import a key that has same name as an existing key, the original key is updated with the values specified in the new key. 可以使用密钥的特定于版本的 URI 来访问以前的版本。You can access the previous version by using the version-specific URI of the key. 例如:For example:

  • 使用 https://vault10.vault.local.azurestack.external:443/keys/key01 总能获得当前版本。Use https://vault10.vault.local.azurestack.external:443/keys/key01 to always get the current version.
  • 使用 https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a 获取此特定版本。Use https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a to get this specific version.

获取密钥Get a key

使用 Get-AzureKeyVaultKey cmdlet 读取密钥及其详细信息:Use the Get-AzureKeyVaultKey cmdlet to read a key and its details:

Get-AzureKeyVaultKey -VaultName "Vault01" -Name "Key01"

创建机密Create a secret

使用 Set-AzureKeyVaultSecret cmdlet 创建或更新保管库中的机密。Use the Set-AzureKeyVaultSecret cmdlet to create or update a secret in a vault. 如果机密尚不存在,则会创建机密。A secret is created if one does not already exist. 如果机密已存在,则会创建机密的新版本:A new version of the secret is created if it already exists:

$secretvalue = ConvertTo-SecureString "User@123" -AsPlainText -Force
Set-AzureKeyVaultSecret -VaultName "Vault01" -Name "Secret01" -SecretValue $secretvalue

在 Powershell 中创建机密

获取机密Get a secret

使用 Get-AzureKeyVaultSecret cmdlet 读取密钥保管库中的机密。Use the Get-AzureKeyVaultSecret cmdlet to read a secret in a key vault. 此命令可以返回所有版本或特定版本的机密:This command can return all or specific versions of a secret:

Get-AzureKeyVaultSecret -VaultName "Vault01" -Name "Secret01"

创建密钥和机密以后,即可授权外部应用使用它们。After you create the keys and secrets, you can authorize external apps to use them.

授权应用使用密钥或机密Authorize an app to use a key or secret

使用 Set-AzureRmKeyVaultAccessPolicy cmdlet 授权应用访问密钥保管库中的密钥或机密。Use the Set-AzureRmKeyVaultAccessPolicy cmdlet to authorize an app to access a key or secret in the key vault.

在以下示例中,保管库名称为 ContosoKeyVault,要授权的应用的客户端 ID 为 8f8c4bbd-485b-45fd-98f7-ec6300b7b4edIn the following example, the vault name is ContosoKeyVault, and the app you want to authorize has a client ID of 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed. 若要授权此应用,请运行以下命令。To authorize the app, run the following command. 也可指定 PermissionsToKeys 参数,为用户、应用或安全组设置权限。You can also specify the PermissionsToKeys parameter to set permissions for a user, an app, or a security group.

对 ADFS 配置的 Azure Stack Hub 环境使用 Set-AzureRmKeyvaultAccessPolicy 时,应提供参数 BypassObjectIdValidationWhen using Set-AzureRmKeyvaultAccessPolicy against an ADFS configured Azure Stack Hub environment, the parameter BypassObjectIdValidation should be provided

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

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

Set-AzureRmKeyVaultAccessPolicy -VaultName 'ContosoKeyVault' -ServicePrincipalName 8f8c4bbd-485b-45fd-98f7-ec6300 -PermissionsToKeys Get -BypassObjectIdValidation

后续步骤Next steps