Import-AadrmTpd
Imports a TPD from AD RMS for Rights Management.
Syntax
Import-AadrmTpd
[-Force]
-TpdFile <String>
-ProtectionPassword <SecureString>
[-HsmKeyFile <String>]
[-FriendlyName <String>]
[-KeyVaultKeyUrl <String>]
[-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 Import-AadrmTpd cmdlet imports an Active Directory Rights Management Services (AD RMS) trusted publishing domain (TPD) over the Internet into your tenant for the Azure Rights Management service so that you can migrate Rights Management from on-premises to the cloud. The TPD contains your private key and RMS templates.
You must use PowerShell to configure your tenant key; you cannot do this configuration by using a management portal.
This cmdlet always sets the key from the imported TPD to an archived state. After you run this command, the key in the imported TPD becomes available to Azure Rights Management to consume content that AD RMS protected by using this key. Use the Set-AadrmKeyProperties cmdlet to change the state of the imported TPD to Active.
Warning: Do not run this cmdlet unless you have read and understood the requirements, restrictions, instructions, and implications of migrating from AD RMS. For more information, see Migrating from AD RMS to Azure Information Protection.
If you migrate templates from your AD RMS as active, you can edit these templates in the Azure portal, or by using PowerShell. You can publish these templates so that users can select them from applications. If the migrated templates are not activated, they can only be used to open documents that they previously protected.
You must use the AD RMS management console to export the TPD. If you use a hardware security module (HSM) for your keys, you must first repackage the TPD keys by using the Azure Key Vault BYOK tools. You can download these tools from the Microsoft Download Site. For more information, see How to generate and transfer HSM-protected keys for Azure Key Vault.
Examples
Example 1: Import TPD with a software key
PS C:\>$Password = Read-Host -AsSecureString -Prompt "Password: "
PS C:\> Import-AadrmTpd -TpdFile "C:\rms_tpd.xml" -ProtectionPassword $Password -Verbose
The first command creates a password as a secure string by using the Read-Host cmdlet, and then stores the secure string in the $Password variable. For more information, type Get-Help Read-Host
.
The second command imports a TPD with a software key.
Example 2: Import TPD with an HSM key
PS C:\>$Password = Read-Host -AsSecureString -Prompt "Password: "
PS C:\> Import-AadrmTpd -TpdFile "C:\no_key_tpd.xml" -ProtectionPassword $Password -KeyVaultKeyUrl "https://contoso-byok-kv.vault.azure.net/keys/contosorms-byok/aaaabbbbcccc111122223333" -FriendlyName "Contoso BYOK key" -Verbose
The first command creates a password as a secure string, and then stores the secure string in the $Password variable.
The second command imports a TPD to be used with a key that is stored in Azure Key Vault. Additionally, the command changes the friendly name of the key to "Contoso BYOK key".
Our example uses the key vault name of contoso-byok-kv, the key name of contosorms-byok, and the version number of aaaabbbbcccc111122223333.
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 |
-FriendlyName
Specifies the friendly name of a trusted publishing domain (TPD) and the SLC key that you imported from AD RMS. If users run Office 2016 or Office 2013, specify the same Friendly name value that is set for the AD RMS cluster properties on the Server Certificate tab.
This parameter is optional. If you don't use it, the key identifier is used instead.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-HsmKeyFile
Specifies the packaged legacy HSM file that was prepared by using the Azure RMS BYOK tools to upload to your tenant key over the Internet.
This parameter is deprecated now that the Azure Rights Management service supports Azure Key Vault, and this parameter is replaced with KeyVaultKeyUrl.
If this parameter and the KeyVaultKeyUrl parameter are both supplied, this parameter is ignored.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
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 your tenant key. This key will be used by the Azure Rights Management service as the root key for all cryptographic operations for your tenant.
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-ProtectionPassword
Specifies the password that was used to encrypt the exported TPD file.
You can use either ConvertTo-SecureString -AsPlaintext or Read-Host to specify the SecureString.
When you use ConvertTo-SecureString and the password has special characters, enter the password between single quotes or escape the special characters. If you do not, the password will not parse correctly and in verbose mode, you will see the following error messages:
VERBOSE: Trusted Publishing Domain data is corrupted. VERBOSE: The remote server returned an unexpected response: (400) Bad Request.
For example, if your password is Pa$$word, enter 'Pa$$word' or Pa`$`$word so that Windows PowerShell can correctly parse the special characters. As a full example, you might type $pwd = ConvertTo-SecureString 'Pa$$w0rd' -AsPlainText -Force and then to check that the stored value is correct, type $pwd to confirm that Pa$$word is displayed.
Type: | SecureString |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-TpdFile
Specifies the TPD file exported from your AD RMS cluster to import to your tenant to use for the Azure Rights Management service.
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 |