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

  • 项目

本文介绍如何使用 PowerShell 在 Azure Stack Hub 中创建和管理密钥保管库。 了解如何使用 Key Vault PowerShell cmdlet 执行以下操作：

  • 创建密钥保管库。
  • 存储和管理加密密钥和机密。
  • 授权用户或应用调用保管库中的操作。

注意

本文中介绍的 Key Vault PowerShell cmdlet 在 Azure PowerShell SDK 中提供。

先决条件

启用适用于 Key Vault 操作的租户订阅

在对某个密钥保管库发出任何操作之前，必须确保租户订阅可以进行保管库操作。 若要验证密钥保管库操作是否已启用，请运行以下命令：

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

如果订阅可以进行保管库操作，则输出会显示某个密钥保管库的所有资源类型的“RegistrationState”为“已注册”。

Key vault registration state in Powershell

如果未启用保管库操作，请发出以下命令，以便在订阅中注册 Key Vault 服务：

Register-AzResourceProvider -ProviderNamespace Microsoft.KeyVault

如果注册成功，则返回以下输出：

Key vault registration in Powershell successful

调用密钥保管库命令时，可能会遇到错误，例如“该订阅未注册为使用命名空间 'Microsoft.KeyVault'”。如果遇到错误，请确认已按照前面的说明启用 Key Vault 资源提供程序。

创建密钥保管库

在创建密钥保管库之前，请创建资源组，使得与密钥保管库相关的所有资源都存在于一个资源组中。 使用以下命令来创建新资源组：

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

New resource group generated in Powershell

现在，请使用以下 cmdlet 在以前创建的资源组中创建一个密钥保管库。 此命令读取三个必需参数：资源组名称、密钥保管库名称和地理位置。

运行以下命令，创建密钥保管库：

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

New key vault generated in Powershell

此命令的输出会显示创建的密钥保管库的属性。 当应用访问此保管库时，它必须使用“保管库 URI”属性（在本例中为 https://vault01.vault.local.azurestack.external）。

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

在 AD FS 部署中，可能会收到此警告：“未设置访问策略。 没有用户或应用程序具有使用此保管库所需的访问权限。”若要解决此问题，请通过 Set-AzKeyVaultAccessPolicy 命令设置保管库的访问策略：

# 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-AzKeyVaultAccessPolicy -VaultName "{key vault name}" -ResourceGroupName "{resource group name}" -ObjectId "{object SID}" -PermissionsToKeys {permissionsToKeys} -PermissionsToSecrets {permissionsToSecrets} -BypassObjectIdValidation

管理密钥和机密

创建保管库后，使用以下步骤来创建并管理保管库中的密钥和机密。

创建密钥

使用 Add-AzureKeyVaultKey cmdlet 在密钥保管库中创建或导入受软件保护的密钥：

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

可以使用 -Destination 参数来指出密钥是受软件保护的。 成功创建密钥后，此命令会输出已创建密钥的详细信息。

New key vault key generated in Powershell

现在可以通过已创建密钥的 URI 来引用该密钥。 如果创建或导入的密钥的名称与现有密钥相同，则会使用新密钥中指定的值来更新原始密钥。 可以使用密钥的特定于版本的 URI 来访问以前的版本。 例如：

  • 使用 https://vault10.vault.local.azurestack.external:443/keys/key01 总能获得当前版本。
  • 使用 https://vault010.vault.local.azurestack.external:443/keys/key01/d0b36ee2e3d14e9f967b8b6b1d38938a 获取此特定版本。

获取密钥

使用 Get-AzureKeyVaultKey cmdlet 读取密钥及其详细信息：

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

创建机密

使用 Set-AzureKeyVaultSecret cmdlet 创建或更新保管库中的机密。 如果机密尚不存在，则会创建机密。 如果机密已存在，则会创建机密的新版本：

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

Create a secret in Powershell

获取机密

使用 Get-AzureKeyVaultSecret cmdlet 读取密钥保管库中的机密。 此命令可以返回所有版本或特定版本的机密：

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

创建密钥和机密以后，即可授权外部应用使用它们。

授权应用使用密钥或机密

使用以下 cmdlet 授权应用访问密钥保管库中的密钥或机密。

在以下示例中，保管库名称为 ContosoKeyVault，要授权的应用的客户端 ID 为 8f8c4bbd-485b-45fd-98f7-ec6300b7b4ed。 若要授权此应用，请运行以下命令。 也可指定 PermissionsToKeys 参数，为用户、应用或安全组设置权限。

对 AD FS 配置的 Azure Stack Hub 环境使用 cmdlet 时，应提供参数 BypassObjectIdValidation

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

如果要授权同一应用读取保管库中的机密，请运行以下 cmdlet：

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

后续步骤