Import-AipServiceTpd
Imports a TPD from AD RMS for Azure Information Protection.
Syntax
Default (Default)
Import-AipServiceTpd
[-Force]
-TpdFile <String>
-ProtectionPassword <SecureString>
[-FriendlyName <String>]
[-KeyVaultKeyUrl <String>]
[-WhatIf]
[-Confirm]
[<CommonParameters>]
Description
The Import-AipServiceTpd cmdlet imports an Active Directory Rights Management Services (AD RMS) trusted publishing domain (TPD) over the Internet into your tenant for Azure Information Protection, so that you can migrate your protection service from on-premises to the cloud. The TPD contains your private key and protection templates from AD RMS.
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 Information Protection to consume content that AD RMS protected by using this key. Use the Set-AipServiceKeyProperties 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 Information Protection.
If you migrate templates from 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. 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-AipServiceTpd -TpdFile "C:\aipservice_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-AipServiceTpd -TpdFile "C:\no_key_tpd.xml" -ProtectionPassword $Password -KeyVaultKeyUrl "https://contoso-byok-kv.vault.azure.net/keys/contosoaipservice-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 contosoaipservice-byok, and the version number of aaaabbbbcccc111122223333.
Parameters
-Confirm
Prompts you for confirmation before running the cmdlet.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Force
Forces the command to run without asking for user confirmation.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | True |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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 Azure Information Protection as the root key for all cryptographic operations for your tenant.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | True |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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.
Parameter properties
| Type: | SecureString |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-TpdFile
Specifies the TPD file exported from your AD RMS cluster to import to your tenant to use for Azure Information Protection.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | False |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.