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.
Syntax
Set-AIPFileLabel
-LabelId <Guid>
[-JustificationMessage <String>]
[-Owner <String>]
[-PreserveFileDetails]
[-EnableTracking]
[-Path] <String[]>
[<CommonParameters>]
Set-AIPFileLabel
-LabelId <Guid>
[-JustificationMessage <String>]
-CustomPermissions <AIPCustomPermissions>
[-Owner <String>]
[-PreserveFileDetails]
[-Path] <String[]>
[<CommonParameters>]
Set-AIPFileLabel
[-JustificationMessage <String>]
[-RemoveLabel]
[-PreserveFileDetails]
[-Path] <String[]>
[<CommonParameters>]
Set-AIPFileLabel
[-JustificationMessage <String>]
[-RemoveLabel]
[-RemoveProtection]
[-PreserveFileDetails]
[-Path] <String[]>
[<CommonParameters>]
Set-AIPFileLabel
[-JustificationMessage <String>]
[-RemoveProtection]
[-PreserveFileDetails]
[-Path] <String[]>
[<CommonParameters>]
Set-AIPFileLabel
-CustomPermissions <AIPCustomPermissions>
[-Owner <String>]
[-PreserveFileDetails]
[-Path] <String[]>
[<CommonParameters>]
Description
For the AIP unified labeling client, the Set-AIPFileLabel cmdlet sets or removes a sensitivity label for one or more files. This action can automatically apply protection when labels are configured to apply encryption.
Additionally, you can use this cmdlet to apply custom permissions when they are created as an ad-hoc protection policy object with the New-AIPCustomPermissions cmdlet.
When the command runs successfully, any existing label or protection can be replaced.
You can run this cmdlet non-interactively. For more information, see the Unified labeling client admin guide.
Note
When running the Set-AIPFileLabel cmdlet in a loop, add these two lines after the cmdlet:
[GC]::Collect()
[GC]::WaitForPendingFinalizers()
Examples
Example 1: Apply the "General" label to all files that do not currently have a label
PS C:\> Get-AIPFileStatus -Path \\Finance\Projects\ | where {$_.IsLabeled -eq $False} | Set-AIPFileLabel -LabelId d9f23ae3-4321-4321-4321-f515f824c57b
FileName Status Comment
-------- ------ ------------
\\Finance\Projects\Image.jpg Success
\\Finance\Projects\Pricelist.pdf Success
\\Finance\Projects\Announcement.docx Success
\\Finance\Projects\Analysis.xlsx Success
This command first identifies all files that are not labeled by using the Get-AIPFileStatus cmdlet. Then, these files are labeled by specifying the "General" label by its ID.
Example 2: Apply the "General" label to .docx files that are not labeled
PS C:\> Get-ChildItem C:\Projects\*.docx -File -Recurse | Get-AIPFileStatus | where {$_.IsLabeled -eq $False} | Set-AIPFileLabel -LabelId d9f23ae3-1234-1234-1234-f515f824c57b
FileName Status Comment
-------- ------ ------------
C:\Projects\Analysis.docx Success
C:\Projects\Projects.docx Success
This command first identifies all .docx files in the C:\Projects folder (and its subfolders) by using Get-Child-Item, then finds from these files the ones that are not labeled by using the Get-AIPFileStatus cmdlet. The resulting files are then labeled by specifying the "General" label by its ID.
Note
This command makes use of the Path alias of FullName, so that Get-Child-Item can be used with Get-AIPFileStatus.
Example 3: (Unified labeling client only) Apply the "General" label to all files in a folder and any of its subfolders
PS C:\> Set-AIPFileLabel -Path C:\Projects\ -LabelId d9f23ae3-1324-1234-1234-f515f824c57b
FileName Status Comment
-------- ------ ------------
C:\Projects\Project1.docx Success
C:\Projects\Datasheet.pdf Success
C:\Projects\Image.jpg Success
C:\Projects\Analysis.xlsx Skipped No label to apply
C:\Projects\Dashboard.xlsx Success
This command sets a label named "General" on all files in the Projects folder and any of its subfolders.
If the General label is configured to apply encryption, the files that were successfully labeled with this command will also be encrypted. In this case, the Rights Management owner (who has the Rights Management Full Control permission) of these files is the user who ran the PowerShell command.
In this example, one file was not labeled (skipped) because it required justification. This might be the intended outcome to ensure that a file with a higher classification label or protection isn't accidentally overwritten with a lower classification label or has protection removed.
To enable this safeguard, the Office 365 classification label policy must be configured to require justification for removing a label or lowering the classification. When you then run this command without the JustificationMessage parameter and the label triggers justification, the file is skipped with the comment "No label to apply".
Example 4: (Unified labeling client only) Apply the "General" label to a single file, which requires justification
PS C:\> Set-AIPFileLabel -Path \\Finance\Projects\Analysis.xlsx -LabelId d9f23ae3-1324-1234-1234-f515f824c57b -JustificationMessage 'The previous label no longer applies'
FileName Status Comment
-------- ------ ------------
\\finance\projects\analysis.xlsx Success
This command sets the "General" label for a file that is already labeled with a higher classification label. The Office 365 classification label policy is configured to require justification for removing a label or lowering the classification. Because the command includes a justification message, the new label is successfully applied.
Example 5: (Unified labeling client only) Remove a label from a file
PS C:\> Set-AIPFileLabel C:\Projects\Analysis.docx -RemoveLabel -JustificationMessage 'The previous label no longer applies'
FileName Status Comment
-------- ------ ------------
C:\Projects\Analysis.docx Success
This command removes the existing label from the file named C:\Projects\Analysis.docx, and specifies a mandatory justification message.
This justification method is required because the relevant Office 365 classification label policy setting is enabled to require justification for removing a label or lowering the classification.
Note
If the label you're removing was protecting your file using a template, this command removes both the label and the protection.
If the label you're removing was protecting your file using custom permissions, this command removes only the label.
Example 6: (Unified labeling client only) Protect a file with custom permissions
PS C:\> $permissions = New-AIPCustomPermissions -Users user1@contoso.com, user2@vanarsdel.com -Permissions Reviewer -ExpirationDate (Get-Date -Month 1 -Day 1 -Year 2020)
PS C:\> Set-AIPFileLabel C:\Projects\Analysis.docx -CustomPermissions $permissions
FileName Status Comment
-------- ------ ------------
C:\Projects\Analysis.docx Success
The first command creates an ad-hoc protection policy object that grants users from different organizations usage rights from the Reviewer permissions, and also applies an expiration date.
The second command protects a single file named Analysis.docx by using the custom permissions in the stored ad-hoc protection policy object.
Example 7: (Unified labeling client only) Apply a label and custom permissions to file
PS C:\> $permissions = New-AIPCustomPermissions -Users a@a.com, b@b.com -Permissions Reviewer
PS C:\> Set-AIPFileLabel C:\Projects\Analysis.docx -LabelId d9f23ae3-1324-1234-1234-f515f824c57b -CustomPermissions $permissions
FileName Status Comment
-------- ------ ------------
C:\Projects\Analysis.docx Success
The first command creates an ad-hoc protection policy object that grants users from different organizations usage rights from the Reviewer permissions, and also applies an expiration date.
The second command applies a label to a single file named Analysis.docx and also protects the file by using the custom permissions in the stored ad-hoc protection policy object. If the label is configured for protection settings, they are replaced by the custom permissions.
Example 8: (Unified labeling client only) Remove protection from a file
PS C:\> Set-AIPFileLabel C:\Projects\Analysis.docx -RemoveProtection
FileName Status Comment
-------- ------ ------------
C:\Projects\Analysis.docx Success
This command removes protection from a single file named Analysis.docx.
Example 9: (Unified labeling client only) Remove protection and a label from a file
PS C:\> Set-AIPFileLabel C:\Projects\Analysis.docx -RemoveProtection -RemoveLabel -JustificationMessage 'The previous label no longer applies'
FileName Status Comment
-------- ------ ------------
C:\Projects\Analysis.docx Success
This command removes the label and custom protection from a single file named Analysis.docx. Because the policy is configured to require justification to remove a label, the justification reason is also supplied so that the command can complete without prompting the user for the reason.
Parameters
-CustomPermissions
Specifies the variable name that stores an ad-hoc protection policy, which was created by using the New-AIPCustomPermissions cmdlet. The ad-hoc protection policy is used to protect the file or files with custom permissions.
Type: | AIPCustomPermissions |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-EnableTracking
Specify this parameter to register a protected document with the document tracking portal.
The user running this cmdlet and global administrators can then track the protected document and if necessary, revoke it. For more information about the document tracking site, see Configuring and using document tracking for Azure Information Protection from the admin guide.
If the label does not apply protection, this parameter is ignored.
Type: | SwitchParameter |
Position: | named |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-JustificationMessage
The justification reason for lowering the classification label, removing a label, or removing protection, if the Azure Information Protection policy requires users to supply this information. If setting a label triggers the justification and this reason is not supplied, the label is not applied. In this case, the status returned is "Skipped" with the comment "Justification required".
Type: | String |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-LabelId
Specifies the identity (ID) of the label to apply. When a label has sublabels, always specify the ID of just a sublabel and not the parent label.
To find the label ID:
The label ID value is not displayed in the Microsoft 365 Compliance center. However, you can use the following Office 365 Security & Compliance Center PowerShell command to find this value: Get-Label | Format-Table -Property DisplayName, Name, Guid
For files that have labels applied, you can also run the Get-AIPFileStatus cmdlet to identify the label ID (MainLabelId or SubLabelId).
Type: | Guid |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-Path
Specifies a local path, network path, or SharePoint Server URL to the files for which you want to get the label and protection information.
Wildcards are not supported and WebDav locations are not supported.
For SharePoint paths, the following are supported:
- SharePoint Server 2019
- SharePoint Server 2016
- SharePoint Server 2013
For example:
- C:\Folder\
- C:\Folder\Filename
- \\Server\Folder
- http://sharepoint.contoso.com/Shared%20Documents/Folder
Paths can include spaces when you enclose the path value with quotes.
Type: | String[] |
Aliases: | FullName, FileName |
Position: | 0 |
Default value: | None |
Required: | True |
Accept pipeline input: | True |
Accept wildcard characters: | False |
-PreserveFileDetails
Specify this parameter to leave the modified date (Windows and SharePoint) and modified by (SharePoint) values unchanged for documents that you label:
For local or network files, the Date modified value remains unchanged.
For SharePoint files, the Modified date and Modified by values remain unchanged.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | False |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-RemoveLabel
Removes any label that has been applied to a file.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
-RemoveProtection
Relevant for: Unified labeling client only
Removes protection from a file. If the file is labeled, the label is not removed.
You must have sufficient usage rights or be a super user for your organization to remove protection from files. For more information, see Configuring super users for Azure Rights Management and discovery services or data recovery.
Use the Set-AIPFileLabel PowerShell cmdlet to enable removal of protection from container files (zip, .rar, .7z, and .pst).
Note
This remove protection capability is disabled by default and must first be enabled using the Set-LabelPolicy cmdlet.
For .pst files, 5 GB is the maximum file size supported with this cmdlet.
Type: | SwitchParameter |
Position: | Named |
Default value: | None |
Required: | True |
Accept pipeline input: | False |
Accept wildcard characters: | False |
Inputs
System.String[]
Outputs
Microsoft.InformationProtection.Powershell.AIP.Results.SetAIPFileResult