< Back
Import-AadrmTpd
Post
NAME Import-AadrmTpd
SYNOPSIS
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 (https://docs.microsoft.com/information- ... -azure-rms).
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 (http://www.microsoft.com/download/details.aspx?id=45345). For more information,
see [How to generate and transfer HSM-protected keys for Azure Key
Vault](https://docs.microsoft.com/azure/key-va ... ected-keys).
PARAMETERS
-Force [<SwitchParameter>]
Forces the command to run without asking for user confirmation.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-FriendlyName <String>
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.
Required? false
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? false
-HsmKeyFile <String>
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.
Required? false
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? false
-KeyVaultKeyUrl <String>
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.
Required? false
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? false
-ProtectionPassword <SecureString>
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.
Required? true
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? false
-TpdFile <String>
Specifies the TPD file exported from your AD RMS server to import to your tenant to use for the Azure Rights
Management service.
Required? true
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? false
-Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
NOTES
---------- 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 ... 1122223333" -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.
RELATED LINKS
Online Version: https://go.microsoft.com/fwlink/?LinkId=521420
Set-AadrmKeyProperties
Migrating from AD RMS to Azure Information Protection
https://docs.microsoft.com/information- ... -azure-rms
How to generate and transfer HSM-protected keys for Azure Key Vault
https://docs.microsoft.com/azure/key-va ... ected-keys
SYNOPSIS
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 (https://docs.microsoft.com/information- ... -azure-rms).
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 (http://www.microsoft.com/download/details.aspx?id=45345). For more information,
see [How to generate and transfer HSM-protected keys for Azure Key
Vault](https://docs.microsoft.com/azure/key-va ... ected-keys).
PARAMETERS
-Force [<SwitchParameter>]
Forces the command to run without asking for user confirmation.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-FriendlyName <String>
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.
Required? false
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? false
-HsmKeyFile <String>
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.
Required? false
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? false
-KeyVaultKeyUrl <String>
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.
Required? false
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? false
-ProtectionPassword <SecureString>
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.
Required? true
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? false
-TpdFile <String>
Specifies the TPD file exported from your AD RMS server to import to your tenant to use for the Azure Rights
Management service.
Required? true
Position? named
Default value None
Accept pipeline input? True (ByPropertyName, ByValue)
Accept wildcard characters? false
-Confirm [<SwitchParameter>]
Prompts you for confirmation before running the cmdlet.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-WhatIf [<SwitchParameter>]
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
NOTES
---------- 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 ... 1122223333" -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.
RELATED LINKS
Online Version: https://go.microsoft.com/fwlink/?LinkId=521420
Set-AadrmKeyProperties
Migrating from AD RMS to Azure Information Protection
https://docs.microsoft.com/information- ... -azure-rms
How to generate and transfer HSM-protected keys for Azure Key Vault
https://docs.microsoft.com/azure/key-va ... ected-keys