Convert-AadrmKeyToKeyVault

Reference

Module:: AADRM

Changes the location of a legacy customer-managed key in Azure Rights Management with the location of a customer-managed key in Azure Key Vault.

Syntax

Convert-AadrmKeyToKeyVault
       -KeyVaultKeyUrl <String>
       -KeyIdentifier <String>
       [-Force]
       [-WhatIf]
       [-Confirm]
       [<CommonParameters>]

Description

Note

This cmdlet from the AADRM module is now deprecated. After July 15, 2020, this cmdlet name will be supported only as an alias to its replacement in the AIPService module.

For more information, see the overview page.

The Convert-AadrmKeyToKeyVault cmdlet is only for customers who have previously created a customer-managed key for the Azure Rights Management service and have received an invitation from Microsoft to migrate their Azure Rights Management tenant key to Azure Key Vault.

Important: Do not run this cmdlet if you have not received this invitation from Microsoft and do not run this cmdlet without assistance from Microsoft.

You must use PowerShell to configure your tenant key; you cannot do this configuration by using a management portal.

Azure RMS now uses Azure Key Vault to manage and monitor a customer-managed Azure RMS tenant key. To create a customer-managed Azure RMS tenant key for the first time, run Use-AadrmKeyVaultKey instead of this cmdlet.

For more information about how to manage your Azure RMS tenant key, see Planning and implementing your Azure Information Protection tenant key.

Before you run this cmdlet, you will need to identify your original customer-managed Azure RMS tenant key. To do that, use the Get-AadrmKeys cmdlet. From the output and identified key, you will need the KeyIdentifier value for the KeyIdentifier parameter when you run this cmdlet.

Also, your organization's administrator for Azure Key Vault must create a new key for Azure RMS and supply you with a URL for this key. You will need to specify the URL for the KeyVaultKeyUrl parameter when you run this cmdlet. This Azure Key Vault administrator must also grant Azure RMS access to the key vault that contains the key.

For security reasons, this cmdlet does not let you change the access control for the key; this must be done from Key Vault.

Examples

Example 1: Change the location of a legacy Azure RMS tenant key with a key in Azure Key Vault

PS C:\>Convert-AadrmKeyToKeyVault -KeyIdentifier aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb -KeyVaultKeyUrl "https://contoso.vault.azure.net/keys/contoso-rms-key/aaaabbbbcccc111122223333"

Changes the location of the original customer-managed key in Azure RMS that has the key identifier of aaaaaaaa-1111-2222-3333-bbbbbbbbbbbb with the location of a customer-managed key in Azure Key Vault, which is named contoso-rms-key and has the version number aaaabbbbcccc111122223333 in the Contoso key vault.

Parameters

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:	SwitchParameter
Aliases:	cf
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-Force

Forces the command to run without asking for user confirmation.

Type:	SwitchParameter
Position:	Named
Default value:	None
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False

-KeyIdentifier

Specifies the key identifier value of the original customer-managed Azure RMS tenant key that you now want to manage from Azure Key Vault.

To get the key identifier value, use the Get-AadrmKeys cmdlet.

Type:	String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-KeyVaultKeyUrl

Specifies the URL of the key in Azure Key Vault that you want to use for the Azure RMS tenant key. This key will be used in Azure RMS as the root key for all cryptographic operations for your Azure RMS tenant.

Type:	String
Position:	Named
Default value:	None
Required:	True
Accept pipeline input:	True
Accept wildcard characters:	False

-WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.

Type:	SwitchParameter
Aliases:	wi
Position:	Named
Default value:	False
Required:	False
Accept pipeline input:	False
Accept wildcard characters:	False