Admin Guide: Using PowerShell with the Azure Information Protection unified client

Applies to: Azure Information Protection, Windows 10, Windows 8.1, Windows 8, Windows Server 2019, Windows Server 2016, Windows Server 2012 R2, Windows Server 2012

If you have Windows 7 or Office 2010, see AIP and legacy Windows and Office versions.

Relevant for: Azure Information Protection unified labeling client for Windows.

When you install the Azure Information Protection unified labeling client, PowerShell commands are automatically installed as part of the AzureInformationProtection module, with cmdlets for labeling.

The AzureInformationProtection module enables you to manage the client by running commands for automation scripts.

For example:

  • Get-AIPFileStatus: Gets the Azure Information Protection label and protection information for a specified file or files.
  • Set-AIPFileClassification: Scans a file to automatically set an Azure Information Protection label for a file, according to conditions that are configured in the policy.
  • Set-AIPFileLabel: Sets or removes an Azure Information Protection label for a file, and sets or removes the protection according to the label configuration or custom permissions.
  • Set-AIPAuthentication: Sets the authentication credentials for the Azure Information Protection client.

The AzureInformationProtection module is installed in the \ProgramFiles (x86)\Microsoft Azure Information Protection folder, and then adds this folder to the PSModulePath system variable. The .dll for this module is named AIP.dll.

Important

The AzureInformationProtection module doesn't support configuring advanced settings for labels or label policies.

For these settings, you need the Office 365 Security & Compliance Center PowerShell. For more information, see Custom configurations for the Azure Information Protection unified labeling client.

Tip

To use cmdlets with path lengths greater than 260 characters, use the following group policy setting that is available starting Windows 10, version 1607:
Local Computer Policy > Computer Configuration > Administrative Templates > All Settings > Enable Win32 long paths

For Windows Server 2016, you can use the same group policy setting when you install the latest Administrative Templates (.admx) for Windows 10.

For more information, see the Maximum Path Length Limitation section from the Windows 10 developer documentation.

Prerequisites for using the AzureInformationProtection module

In addition to the prerequisites for installing the AzureInformationProtection module, there are extra prerequisites for when you use the labeling cmdlets for Azure Information Protection:

  • The Azure Rights Management service must be activated.

    If your Azure Information Protection tenant is not activated, see the instructions for Activating the protection service from Azure Information Protection.

  • To remove protection from files for others using your own account:

    • The super user feature must be enabled for your organization.
    • Your account must be configured to be a super user for Azure Rights Management.

    For example, you may want to remove protection for others for the sake of data discovery or recovery. If you are using labels to apply protection, you can remove that protection by setting a new label that doesn't apply protection, or you can remove the label.

    To remove protection, use the Set-AIPFileLabel cmdlet with the RemoveProtection parameter. The remove protection capability is disabled by default and must first be enabled using the Set-LabelPolicy cmdlet.

RMS to unified labeling cmdlet mapping

If you've migrated from Azure RMS, note that RMS-related cmdlets have been deprecated for use in unified labeling.

Some of the legacy cmdlets have been replaced with new cmdlets for unified labeling. For example, if you used New-RMSProtectionLicense with RMS protection and have migrated to unified labeling, use New-AIPCustomPermissions instead.

The following table maps RMS-related cmdlets with the updated cmdlets used for unified labeling:

RMS cmdlet Unified labeling cmdlet
Get-RMSFileStatus Get-AIPFileStatus
Get-RMSServer Not relevant for unified labeling.
Get-RMSServerAuthentication Set-AIPAuthentication
Clear-RMSAuthentication Set-AIPAuthentication
Set-RMSServerAuthentication Set-AIPAuthentication
Get-RMSTemplate Not relevant for unified labeling
New-RMSProtectionLicense New-AIPCustomPermissions, and Set-AIPFileLabel, with the CustomPermissions parameter
Protect-RMSFile Set-AIPFileLabel, with the RemoveProtection parameter

How to label files non-interactively for Azure Information Protection

By default, when you run the cmdlets for labeling, the commands run in your own user context in an interactive PowerShell session.

For more information, see:

Note

If the computer cannot have internet access, there's no need to create the app in Azure AD and run the Set-AIPAuthentication cmdlet. Instead, follow the instructions for disconnected computers.

Prerequisites for running AIP labeling cmdlets unattended

To run Azure Information Protection labeling cmdlets unattended, use the following access details:

  • A Windows account that can sign in interactively.

  • An Azure AD account, for delegated access. For ease of administration, use a single account that's synchronized from Active Directory to Azure AD.

    For the delegated user account:

    Requirement Details
    Label policy Make sure that you have a label policy assigned to this account and that the policy contains the published labels you want to use.

    If you use label policies for different users, you might need to create a new label policy that publishes all your labels, and publish the policy to just this delegated user account.
    Decrypting content If this account needs to decrypt content, for example, to reprotect files and inspect files that others have protected, make it a super user for Azure Information Protection and make sure the super user feature is enabled.
    Onboarding controls If you have implemented onboarding controls for a phased deployment, make sure that this account is included in your onboarding controls you've configured.
  • An Azure AD access token, which sets and stores credentials for the delegated user to authenticate to Azure Information Protection. When the token in Azure AD expires, you must run the cmdlet again to acquire a new token.

    The parameters for Set-AIPAuthentication use values from an app registration process in Azure AD. For more information, see Create and configure Azure AD applications for Set-AIPAuthentication.

Run the labeling cmdlets non-interactively by first running the Set-AIPAuthentication cmdlet.

The computer running the AIPAuthentication cmdlet downloads the labeling policy that's assigned to your delegated user account in your labeling management center, such as the Microsoft 365 Security & compliance center.

Create and configure Azure AD applications for Set-AIPAuthentication

The Set-AIPAuthentication cmdlet requires an app registration for the AppId and AppSecret parameters.

For users who've recently migrated from the classic client, and had created an app registration for the previous WebAppID and NativeAppId parameters, you'll need to create a new app registration for the unified labeling client.

To create a new app registration for the unified labeling client Set-AIPAuthentication cmdlet:

  1. In a new browser window, sign in the Azure portal to the Azure AD tenant that you use with Azure Information Protection.

  2. Navigate to Azure Active Directory > Manage > App registrations, and select New registration.

  3. On the Register an application pane, specify the following values, and then click Register:

    Option Value
    Name AIP-DelegatedUser
    Specify a different name as needed. The name must be unique per tenant.
    Supported account types Select Accounts in this organizational directory only.
    Redirect URI (optional) Select Web, and then enter https://localhost.
  4. On the AIP-DelegatedUser pane, copy the value for the Application (client) ID.

    The value looks similar to the following example: 77c3c1c3-abf9-404e-8b2b-4652836c8c66.

    This value is used for the AppId parameter when you run the Set-AIPAuthentication cmdlet. Paste and save the value for later reference.

  5. From the sidebar, select Manage > Certificates & secrets.

    Then, on the AIP-DelegatedUser - Certificates & secrets pane, in the Client secrets section, select New client secret.

  6. For Add a client secret, specify the following, and then select Add:

    Field Value
    Description Azure Information Protection unified labeling client
    Expires Specify your choice of duration (1 year, 2 years, or never expires)
  7. Back on the AIP-DelegatedUser - Certificates & secrets pane, in the Client secrets section, copy the string for the VALUE.

    This string looks similar to the following example: OAkk+rnuYc/u+]ah2kNxVbtrDGbS47L4.

    To make sure you copy all the characters, select the icon to Copy to clipboard.

    Important

    It's important that you save this string because it is not displayed again and it cannot be retrieved. As with any sensitive information that you use, store the saved value securely and restrict access to it.

  8. From the sidebar, select Manage > API permissions.

    On the AIP-DelegatedUser - API permissions pane, select Add a permission.

  9. On the Request API permissions pane, make sure that you're on the Microsoft APIs tab, and select Azure Rights Management Services.

    When you're prompted for the type of permissions that your application requires, select Application permissions.

  10. For Select permissions, expand Content and select the following, and then select Add permissions.

    • Content.DelegatedReader
    • Content.DelegatedWriter
  11. Back on the AIP-DelegatedUser - API permissions pane, select Add a permission again.

    On the Request AIP permissions pane, select APIs my organization uses, and search for Microsoft Information Protection Sync Service.

  12. On the Request API permissions pane, select Application permissions.

    For Select permissions, expand UnifiedPolicy, select UnifiedPolicy.Tenant.Read, and then select Add permissions.

  13. Back on the AIP-DelegatedUser - API permissions pane, select Grant admin consent for <your tenant name> and select Yes for the confirmation prompt.

    Your API permissions should look like the following image:

    API permissions for the registered app in Azure AD

Now you've completed the registration of this app with a secret, you're ready to run Set-AIPAuthentication with the parameters AppId, and AppSecret. Additionally, you'll need your tenant ID.

Tip

You can quickly copy your tenant ID by using Azure portal: Azure Active Directory > Manage > Properties > Directory ID.

Running the Set-AIPAuthentication cmdlet

  1. Open Windows PowerShell with the Run as administrator option.

  2. In your PowerShell session, create a variable to store the credentials of the Windows user account that will run non-interactively. For example, if you created a service account for the scanner:

    $pscreds = Get-Credential "CONTOSO\srv-scanner"
    

    You're prompted for this account's password.

  3. Run the Set-AIPAuthentication cmdlet, with the OnBeHalfOf parameter, specifying as its value the variable that you created.

    Also specify your app registration values, your tenant ID, and the name of the delegated user account in Azure AD. For example:

    Set-AIPAuthentication -AppId "77c3c1c3-abf9-404e-8b2b-4652836c8c66" -AppSecret "OAkk+rnuYc/u+]ah2kNxVbtrDGbS47L4" -TenantId "9c11c87a-ac8b-46a3-8d5c-f4d0b72ee29a" -DelegatedUser scanner@contoso.com -OnBehalfOf $pscreds
    

Next steps

For cmdlet help when you are in a PowerShell session, type Get-Help <cmdlet name> -online. For example:

Get-Help Set-AIPFileLabel -online

For more information, see: