Import-​Aadrm​Tpd

Imports a TPD from AD RMS for Rights Management.

Syntax

Import-AadrmTpd
      [-Force]
      [-FriendlyName <String>]
      [-HsmKeyFile <String>]
      [-KeyVaultKeyUrl <String>]
      -ProtectionPassword <SecureString>
      -TpdFile <String>
      [-Confirm]
      [-WhatIf]
      [<CommonParameters>]

Description

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 classic portal. 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. Additionaly command changes 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.

Required Parameters

-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
Accept pipeline input:True (ByPropertyName, ByValue)
Accept wildcard characters:False
-TpdFile

Specifies the TPD file exported from your AD RMS server to import to your tenant to use for the Azure Rights Management service.

Type:String
Position:Named
Default value:None
Accept pipeline input:True (ByPropertyName, ByValue)
Accept wildcard characters:False

Optional Parameters

-Confirm

Prompts you for confirmation before running the cmdlet.

Type:SwitchParameter
Aliases:cf
Position:Named
Default value: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
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
Accept pipeline input:True (ByPropertyName, ByValue)
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
Accept pipeline input:True (ByPropertyName, ByValue)
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
Accept pipeline input:True (ByPropertyName, ByValue)
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
Accept pipeline input:False
Accept wildcard characters:False