如何将 Key Vault 软删除与 PowerShell 配合使用How to use Key Vault soft-delete with PowerShell

Azure Key Vault 的软删除功能允许恢复已删除的保管库和保管库对象。Azure Key Vault's soft-delete feature allows recovery of deleted vaults and vault objects. 软删除将具体探讨以下方案:Specifically, soft-delete addresses the following scenarios:

  • 支持 Key Vault 的可恢复删除Support for recoverable deletion of a key vault
  • 支持密钥保管库对象、密钥、机密和证书的可恢复删除Support for recoverable deletion of key vault objects; keys, secrets, and, certificates

先决条件Prerequisites

备注

本文进行了更新,以便使用新的 Azure PowerShell Az 模块。This article has been updated to use the new Azure PowerShell Az module. 你仍然可以使用 AzureRM 模块,至少在 2020 年 12 月之前,它将继续接收 bug 修补程序。You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. 若要详细了解新的 Az 模块和 AzureRM 兼容性,请参阅新 Azure Powershell Az 模块简介To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. 有关 Az 模块安装说明,请参阅安装 Azure PowerShellFor Az module installation instructions, see Install Azure PowerShell.

备注

环境中可能加载了过期版本的 Key Vault PowerShell 输出格式化文件,而没有加载正确版本。There is an outdated version of our Key Vault PowerShell output formatting file that may be loaded into your environment instead of the correct version. 预期 PowerShell 的更新版本将包含输出格式所需的更正,届时将更新此主题。We are anticipating an updated version of PowerShell to contain the needed correction for the output formatting and will update this topic at that time. 如果遇到此格式问题,当前的解决方法是:The current workaround, should you encounter this formatting problem, is:

  • 如果发现未看到此主题中所述的已启用软删除的属性,请使用以下查询:$vault = Get-AzKeyVault -VaultName myvault; $vault.EnableSoftDeleteUse the following query if you notice you're not seeing the soft-delete enabled property described in this topic: $vault = Get-AzKeyVault -VaultName myvault; $vault.EnableSoftDelete.

有关适用于 PowerShell 的密钥保管库特定引用信息,请参阅 Azure 密钥保管库 PowerShell 引用For Key Vault specific reference information for PowerShell, see Azure Key Vault PowerShell reference.

所需的权限Required permissions

Key Vault 操作通过基于角色的访问控制 (RBAC) 权限单独管理,如下所示:Key Vault operations are separately managed via role-based access control (RBAC) permissions as follows:

OperationOperation 说明Description 用户权限User permission
列出List 列出已删除的密钥保管库。Lists deleted key vaults. Microsoft.KeyVault/deletedVaults/readMicrosoft.KeyVault/deletedVaults/read
恢复Recover 还原已删除的密钥保管库。Restores a deleted key vault. Microsoft.KeyVault/vaults/writeMicrosoft.KeyVault/vaults/write
清除Purge 永久删除已删除的密钥保管库及其所有内容。Permanently removes a deleted key vault and all its contents. Microsoft.KeyVault/locations/deletedVaults/purge/actionMicrosoft.KeyVault/locations/deletedVaults/purge/action

有关权限和访问控制的详细信息,请参阅保护 Key VaultFor more information on permissions and access control, see Secure your key vault.

启用软删除Enabling soft-delete

启用“软删除”以允许恢复已删除的密钥保管库或存储在密钥保管库的对象。You enable "soft-delete" to allow recovery of a deleted key vault, or objects stored in a key vault.

重要

在密钥保管库上启用“软删除”是不可逆的操作。Enabling 'soft-delete' on a key vault is an irreversible action. 将软删除属性设置为“true”后,将无法更改或删除该属性。Once the soft-delete property has been set to "true", it cannot be changed or removed.

现有的密钥保管库Existing key vault

对于名为 ContosoVault 的现有密钥保管库,请按如下所示启用软删除。For an existing key vault named ContosoVault, enable soft-delete as follows.

($resource = Get-AzResource -ResourceId (Get-AzKeyVault -VaultName "ContosoVault").ResourceId).Properties | Add-Member -MemberType "NoteProperty" -Name "enableSoftDelete" -Value "true"

Set-AzResource -resourceid $resource.ResourceId -Properties $resource.Properties

新的密钥保管库New key vault

默认对所有新密钥保管库自动启用软删除。Soft delete is automatically on by default for all new key vaults. 2020 年 12 月 31 日前,无法在任何密钥保管库上禁用软删除。By December 31st 2020 it will no longer be possible to disable soft delete on any key vault.

验证软删除支持Verify soft-delete enablement

若要验证密钥保管库是否启用了软删除,请运行“显示”命令,并查看“启用软删除?”To verify that a key vault has soft-delete enabled, run the show command and look for the 'Soft Delete Enabled?' 属性:attribute:

Get-AzKeyVault -VaultName "ContosoVault"

删除由软删除保护的密钥保管库Deleting a soft-delete protected key vault

删除密钥保管库的命令会改变行为,具体取决于是否启用了软删除。The command to delete a key vault changes in behavior, depending on whether soft-delete is enabled.

重要

如果为没有启用软删除的密钥保管库运行以下命令,则将永久删除此密钥保管库及其所有内容,而没有任何恢复选项!If you run the following command for a key vault that does not have soft-delete enabled, you will permanently delete this key vault and all its content with no options for recovery!

Remove-AzKeyVault -VaultName 'ContosoVault'

软删除如何保护密钥保管库How soft-delete protects your key vaults

已启用软删除:With soft-delete enabled:

  • 将已删除的密钥保管库从其资源组中删除,并放置在与其创建位置关联的保留命名空间中。A deleted key vault is removed from its resource group and placed in a reserved namespace, associated with the location where it was created.
  • 只要已删除对象中包含的密钥保管库处于已删除状态,就无法访问这些已删除的对象(如密钥、机密和证书)。Deleted objects such as keys, secrets, and certificates, are inaccessible as long as their containing key vault is in the deleted state.
  • 保留已删除密钥保管库的 DNS 名称,这会阻止创建具有相同名称的新密钥保管库。The DNS name for a deleted key vault is reserved, preventing a new key vault with same name from being created. 

使用以下命令,可查看与订阅关联且处于已删除状态的密钥保管库:You may view deleted state key vaults, associated with your subscription, using the following command:

Get-AzKeyVault -InRemovedState 
  • ID 可用于在恢复或清除时识别资源。ID can be used to identify the resource when recovering or purging.
  • 资源 ID是此保管库的原始资源 ID。Resource ID is the original resource ID of this vault. 由于此密钥保管库现在处于已删除状态,因此该资源 ID 不存在任何资源。Since this key vault is now in a deleted state, no resource exists with that resource ID.
  • “计划清除日期”表示如果不采取任何操作,将永久删除保管库。Scheduled Purge Date is when the vault will be permanently deleted, if no action is taken. 用于计算“计划清除日期”的默认保留期是 90 天。The default retention period, used to calculate the Scheduled Purge Date, is 90 days.

恢复密钥保管库Recovering a key vault

若要恢复密钥保管库,请指定密钥保管库名称、资源组和位置。To recover a key vault, you specify the key vault name, resource group, and location. 请注意已删除的密钥保管库的位置和资源组,以便用于恢复过程。Note the location and the resource group of the deleted key vault, as you need them for the recovery process.

Undo-AzKeyVaultRemoval -VaultName ContosoVault -ResourceGroupName ContosoRG -Location ChinaNorth

恢复密钥保管库后,将使用密钥保管库的原始资源 ID 创建新资源。When a key vault is recovered, a new resource is created with the key vault's original resource ID. 如果删除了原始资源组,则在尝试恢复之前必须创建一个具有相同名称的资源组。If the original resource group is removed, one must be created with same name before attempting recovery.

删除和清除密钥保管库对象Deleting and purging key vault objects

以下命令将删除已启用软删除的名为“ContosoVault”的密钥保管库中的“ContosoFirstKey”密钥:The following command will delete the 'ContosoFirstKey' key, in a key vault named 'ContosoVault', which has soft-delete enabled:

Remove-AzKeyVaultKey -VaultName ContosoVault -Name ContosoFirstKey

为软删除启用密钥保管库后,删除的密钥仍然显示为待删除,除非明确列出已删除的密钥。With your key vault enabled for soft-delete, a deleted key still appears to be deleted, unless you explicitly list deleted keys. 对处于已删除状态的密钥的大多数操作将失败,列出、恢复或清除已删除的密钥除外。Most operations on a key in the deleted state will fail, except for listing, recovering, purging a deleted key.

例如,以下命令可列出“ContosoVault”密钥保管库中的已删除密钥:For example, the following command lists deleted keys in the 'ContosoVault' key vault:

Get-AzKeyVaultKey -VaultName ContosoVault -InRemovedState

转换状态Transition state

在启用了软删除的密钥保管库中删除密钥时,可能需要几秒钟时间完成转换。When you delete a key in a key vault with soft-delete enabled, it may take a few seconds for the transition to complete. 在此转换期间,密钥可能不处于活动状态或已删除状态。During this transition, it may appear that the key is not in the active state or the deleted state.

将软删除用于密钥保管库对象Using soft-delete with key vault objects

就像密钥保管库一样,除非恢复或清除已删除的密钥、机密或证书,否则它将保持已删除状态最多 90 天。Just like key vaults, a deleted key, secret, or certificate, remains in deleted state for up to 90 days, unless you recover it or purge it.

Keys

恢复软删除的密钥:To recover a soft-deleted key:

Undo-AzKeyVaultKeyRemoval -VaultName ContosoVault -Name ContosoFirstKey

永久删除(也称为清除)软删除密钥:To permanently delete (also known as purging) a soft-deleted key:

重要

清除密钥将永久删除,且无法恢复!Purging a key will permanently delete it, and it will not be recoverable!

Remove-AzKeyVaultKey -VaultName ContosoVault -Name ContosoFirstKey -InRemovedState

“恢复”和“清除”操作具有与密钥保管库访问策略相关的各自权限 。The recover and purge actions have their own permissions associated in a key vault access policy. 用户或服务主体如果要执行“恢复”或“清除”操作,必须拥有该密钥或机密的相应权限 。For a user or service principal to be able to execute a recover or purge action, they must have the respective permission for that key or secret. 默认情况下,使用“全部”快捷方式授予所有权限时,“清除”不会添加到密钥保管库访问策略中。By default, purge isn't added to a key vault's access policy, when the 'all' shortcut is used to grant all permissions. 必须明确授予“清除”权限。You must specifically grant purge permission.

设置密钥保管库访问策略Set a key vault access policy

以下命令授予 user@contoso.com 对“ContosoVault”中的密钥执行多项操作(包括“清除”)的权限:The following command grants user@contoso.com permission to use several operations on keys in ContosoVault including purge:

Set-AzKeyVaultAccessPolicy -VaultName ContosoVault -UserPrincipalName user@contoso.com -PermissionsToKeys get,create,delete,list,update,import,backup,restore,recover,purge

备注

如果现有密钥保管库刚刚启用软删除,则可能没有“恢复”和“清除”权限 。If you have an existing key vault that has just had soft-delete enabled, you may not have recover and purge permissions.

机密Secrets

像密钥一样,可以使用自己的命令管理机密:Like keys, secrets are managed with their own commands:

  • 删除名为 SQLPassword 的机密:Delete a secret named SQLPassword:

    Remove-AzKeyVaultSecret -VaultName ContosoVault -name SQLPassword
    
  • 列出密钥保管库中所有已删除的机密:List all deleted secrets in a key vault:

    Get-AzKeyVaultSecret -VaultName ContosoVault -InRemovedState
    
  • 恢复处于已删除状态的机密:Recover a secret in the deleted state:

    Undo-AzKeyVaultSecretRemoval -VaultName ContosoVault -Name SQLPAssword
    
  • 清除处于已删除状态的机密:Purge a secret in deleted state:

    重要

    清除机密将永久删除,且无法恢复!Purging a secret will permanently delete it, and it will not be recoverable!

    Remove-AzKeyVaultSecret -VaultName ContosoVault -InRemovedState -name SQLPassword
    

证书Certificates

可以使用以下命令管理证书:You can manage certificates using below commands:

  • 删除证书:Delete a Certificate:

    Remove-AzKeyVaultCertificate -VaultName ContosoVault -Name 'MyCert'
    
  • 列出密钥保管库中所有已删除的证书:List all deleted certificates in a key vault:

    Get-AzKeyVaultCertificate -VaultName ContosoVault -InRemovedState
    
  • 恢复处于已删除状态的证书:Recover a certificate in the deleted state:

    Undo-AzKeyVaultCertificateRemoval -VaultName ContosoVault -Name 'MyCert'
    
  • 清除处于已删除状态的证书:Purge a certificate in deleted state:

    重要

    清除证书时会永久删除证书,并且无法恢复!Purging a certificate will permanently delete it, and it will not be recoverable!

    Remove-AzKeyVaultcertificate -VaultName ContosoVault -Name 'MyCert' -InRemovedState 
    

清除由软删除保护的密钥保管库Purging a soft-delete protected key vault

重要

清除密钥保管库或其包含的对象之一将永久删除它,这意味着无法恢复!Purging a key vault or one of its contained objects, will permanently delete it, meaning it will not be recoverable!

清除功能用于永久删除以前已软删除的密钥保管库对象或整个密钥保管库。The purge function is used to permanently delete a key vault object or an entire key vault, that was previously soft-deleted. 如前一部分中所示,启用了软删除功能的密钥保管库中存储的对象可能会经历多个状态:As demonstrated in the previous section, objects stored in a key vault with the soft-delete feature enabled, can go through multiple states:

  • 活动:删除之前。Active: before deletion.
  • 已软删除:删除之后,能够列出和恢复为活动状态。Soft-Deleted: after deletion, able to be listed and recovered back to active state.
  • 已永久删除:清除之后,不能恢复。Permanently-Deleted: after purge, not able to be recovered.

对于密钥保管库同样如此。The same is true for the key vault. 若要永久删除已软删除的密钥保管库及其内容,必须清除密钥保管库本身。In order to permanently delete a soft-deleted key vault and its contents, you must purge the key vault itself.

清除密钥保管库Purging a key vault

清除密钥保管库时,将永久删除其全部内容,包括密钥、机密和证书。When a key vault is purged, its entire contents are permanently deleted, including keys, secrets, and certificates. 若要清除已软删除的密钥保管库,请使用具有 -InRemovedState 选项的命令 Remove-AzKeyVault,并通过使用 -Location location 参数指定已删除的密钥保管库的位置。To purge a soft-deleted key vault, use the Remove-AzKeyVault command with the option -InRemovedState and by specifying the location of the deleted key vault with the -Location location argument. 可以使用命令 Get-AzKeyVault -InRemovedState 查找已删除的保管库的位置。You can find the location of a deleted vault using the command Get-AzKeyVault -InRemovedState.

Remove-AzKeyVault -VaultName ContosoVault -InRemovedState -Location chinanorth

所需的清除权限Purge permissions required

  • 要清除已删除的密钥保管库,用户需要 Microsoft.KeyVault/locations/deletedVaults/purge/action 操作的 RBAC 权限。To purge a deleted key vault, the user needs RBAC permission to the Microsoft.KeyVault/locations/deletedVaults/purge/action operation.
  • 要列出已删除的密钥保管库,用户需要 Microsoft.KeyVault/deletedVaults/read 操作的 RBAC 权限。To list a deleted key vault, the user needs RBAC permission to the Microsoft.KeyVault/deletedVaults/read operation.
  • 默认情况下,只有订阅管理员具有这些权限。By default only a subscription administrator has these permissions.

计划清除Scheduled purge

列出已删除的密钥保管库对象还会显示 Key Vault 计划将其清除的时间。Listing deleted key vault objects also shows when they're scheduled to be purged by Key Vault. “计划清除日期”指示如果不采取任何操作,将永久删除密钥保管库对象的时间。Scheduled Purge Date indicates when a key vault object will be permanently deleted, if no action is taken. 默认情况下,已删除的密钥保管库对象的保留期为 90 天。By default, the retention period for a deleted key vault object is 90 days.

重要

已清除的保管库对象(由“计划清除日期”字段触发清除操作)将被永久删除。A purged vault object, triggered by its Scheduled Purge Date field, is permanently deleted. 不可恢复!It is not recoverable!

启用清除保护Enabling Purge Protection

启用清除保护时,在保持期到期之前,不能清除处于已删除状态的保管库或对象。When purge protection is turned on, a vault or an object in deleted state cannot be purged until the retention period has passed. 仍可以恢复此类保管库或对象。Such vault or object can still be recovered. 此功能可增加保障,在保留期到期之前,永远不会永久删除保管库或对象。This feature gives added assurance that a vault or an object can never be permanently deleted until the retention period has passed. 默认保持期为 90 天,但在创建密钥保管库期间,可将保留策略间隔设置为介于 7 到 90 天之间的值。The default retention period is 90 days but, during key vault creation, it is possible to set the retention policy interval to a value from 7 to 90 days. 清除保护保留策略使用相同的间隔。The purge protection retention policy uses the same interval. 一旦设置,保留策略间隔就不能再更改。Once set, the retention policy interval cannot be changed.

仅当也启用了软删除时,才能启用清除保护。You can enable purge protection only if soft-delete is also enabled. 不支持禁用清除保护。Disabling purge protection isn't supported.

若要在创建保管库时同时启用软删除和清除保护,请使用 New-AzKeyVault cmdlet:To turn on both soft delete and purge protection when creating a vault, use the New-AzKeyVault cmdlet:

New-AzKeyVault -Name ContosoVault -ResourceGroupName ContosoRG -Location chinanorth -EnableSoftDelete -EnablePurgeProtection

若要向现有保管库(已启用软删除)添加清除保护,请使用 Get-AzKeyVaultGet-AzResourceSet-AzResource cmdlet:To add purge protection to an existing vault (that already has soft delete enabled), use the Get-AzKeyVault, Get-AzResource, and Set-AzResource cmdlets:

($resource = Get-AzResource -ResourceId (Get-AzKeyVault -VaultName "ContosoVault").ResourceId).Properties | Add-Member -MemberType "NoteProperty" -Name "enablePurgeProtection" -Value "true"

Set-AzResource -resourceid $resource.ResourceId -Properties $resource.Properties

其他资源Other resources