AIP Templates
Now we are looking for Azure Information Protection templates. We can find them like so:
Get-AipServiceTemplate
We see that there are two default templates, located in the red rectangles, and in this tenant, we also have two administrator created AIP Templates:
As usual with AIP Templates, we don’t have a lot to go on in our resulting Properties as shown above. Let’s see what other cmdlets we may have available for templates:
Get-Command *aip*template*
We see these cmdlets available:
Add-AipServiceTemplate Export-AipServiceTemplate Get-AipServiceTemplate Get-AipServiceTemplateProperty Import-AipServiceTemplate Remove-AipServiceTemplate Set-AipServiceTemplateProperty
Interesting. We have a couple of cmdlets with ‘TemplateProperty’ at the end of the cmdlet name. Wonder what these do?
Get-Help Get-AipServiceTemplateProperty -Examples
What are our available switches and parameters:
Exporting and Importing AIP Templates
A pair of PowerShell cmdlets exists that enables the exporting of AIP Templates from one Office 365 tenant to another Office 365 tenant. These cmdlets are:
Export-AIPServiceTemplate Import-AIPServiceTemplate
Why would we want to move templates? Possibly during a consolidation of multiple tenants owned by subsidiaries or possibly the movement to a new tenant with a new namespace / name. We would use these cmdlets to assist with moving our templates then. Let’s explore how these work.
Example
For this example we have Tenant A and Tenant B. Tenant B is one that is owned by a subsidiary that now is to be absorbed by the parent company. As such, we need to move all aspects that we can from Tenant B to Tenant A and this includes our AIP Templates. These templates are crucial to how this subsidiary was conducting business and would like to continue using them. First, we need to get an inventory of the AIP Templates that are present:
Get-AIPServiceTemplate
From the above we can see that there are two default templates and two templates that were created which means we only really need to export the last two templates for our tenant move.
Let’s check to see what is needed in order to first export and then to import a template:
Get-Help Export-AIPServiceTemplate -Examples
It appears that we need to specify a path and a template ID. So let’s go ahead and export those two templates to a directory on our workstation:
Export-AipServiceTemplate -Path c:\Templates\ViewOnly.xml -TemplateId aff4c520-f29d-412d-8229-7dc23eb6b186 Export-AipServiceTemplate -Path c:\Templates\Encryption.xml -TemplateId 6647e52d-98d7-4918-8c6f-f9cd6b57f07b
Which provides us with these results:
The XML files look like this:
And
Now that we’ve exported the XML templates, how do we import?
Get-Help Import-AipServiceTemplate -Examples
For this import, we are assuming that we’ve already made a connection to Tenant A and are connected to the AIP Service in particular. We then run this cmdlet to import one of the templates we exported previously:
Import-AipServiceTemplate -Path c:\Templates\ViewOnly.xml
We can perform the same action one more time with the other template:
Import-AipServiceTemplate -Path c:\Templates\Encryption.xml
And now we have all of our unique AIP Service Templates imported into Tenant A.
Creating a new template
When creating AIP Templates for your tenant, there are two choices – AIP interface in the Azure Portal or with PowerShell.
How do we do this in PowerShell? First, let’s check to see if we have any helpful examples in PowerShell:
Get-Help Add-AipServiceTemplate -Examples
Well, that certainly looks like fun. One of the things you see right off the bat is that there are multiple descriptions with a number following the variable name ‘[1033]’ and ‘[1034]’. They are obviously for different languages (we can see the text being stored), but if we wanted to do this how would we know what the valid values for the language would be?
Do a little research on the Internet and we find that these are based off known international standards:
https://www.science.co.il/language/Locale-codes.php
And then trace this back to:
https://docs.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085406-a698-4e12-9d4d-c3b0ee3dbc4a
Then we can see the two example languages above (1033 and 1034) are listed in the chart from the Microsoft reference page:
For the first example, we will create a AIP Template for users in the US, France and Germany … (please forgive any bad translations as I am not a native German/French speaker). This template will be used to restrict emails to view-only for any recipients that receive them applied to an email. Let’s follow the example provided by Microsoft and so we can understand what we are doing.
First, we need a hash table to store all of the names for the three languages:
$Names = @{}
Then we create one name for each language, remembering to use the regional codes for each language which are 1033, 1036 and 1031 for English, French and German.
$Names[1033] = "View Only" $Names[1036] = "Affichage Uniquement" $Names[1031] = "Nur anzeigen"
Next we need a hash table to store all of the descriptions in different languages:
$Descriptions = @{}
And
$Descriptions[1033] = "This content is view-only and intended to restrict recipient access." $Descriptions[1036] = "Ce contenu est en lecture seule et vise à restreindre l'accès des destinataires." $Descriptions[1031] = "Dieser Inhalt ist schreibgeschützt und soll den Empfängerzugriff einschränken."
Defining rights for the template takes an entirely different cmdlet called ‘New-AipServiceRightsDefinition’ and with this cmdlet we need to specify what rights are granted and to who. For this example we will restrict the document when sent to the Marketing and ResearchAndDevelopment departments.
Get-Help New-AipServiceRightsDefinition -Examples
In our case we will create two of these definitions and assign the ‘VIEW’ right:
$RightsDefinition1 = New-AipServiceRightsDefinition -EmailAddress marketing@practicalpowershell.com -Rights VIEW $RightsDefinition2 = New-AipServiceRightsDefinition -EmailAddress rnd@practicalpowershell.com -Rights VIEW
We also need to decide on how long a user can be offline before validating their license. The IT Manager wants seven days in order to allow for someone who is on short vacation or out sick to have access as needed.
Now that we have all the information we need, we can add the template to the AIP Service:
Add-AipServiceTemplate -Names $Names -Descriptions $Descriptions -LicenseValidityDuration 7 -RightsDefinitions $RightsDefinition1,$RightsDefinition2 -ScopedIdentities IT@practicalpowershell.com -Status Archived
Notice that the status is set to Archived. This is done so we can validate the template before publishing the template… and we can publish the template, as shown below:
Set-AipServiceTemplateProperty -TemplateID <New Template ID> -Status Published
Now we have a new template that we can use in Exchange Online.
Removing an old template:
What if we had some old AIP Service Templates, we can use the Remove-AIPServiceTemple. First, let’s check the cmdlet examples:
Get-Help Remove-AipServiceTemplate -Examples
The one-liner in the above example is self-explanatory. We simply need the TemplateID to remove a template:
Remove-AipServiceTemplate -TemplateId aff4c520-f29d-412d-8229-7dc23eb6b186
Which provides us with this:
TIP: Connection Errors in AIP Service
In multiple instances, a cmdlet in the AIP Service would fail like so:
The solution in 99% of the cases is to run ‘Connect-AIPService’ once more and the cmdlet will run fine.
