Set-FileLabel
Sets the sensitivity label and protection for a file through manual labeling or autolabeling according to the label configuration or custom permissions.
Syntax
SetLabel
Set-FileLabel
[-Path] <String[]>
-LabelId <Guid>
[-JustificationMessage <String>]
[-Owner <String>]
[-PreserveFileDetails]
SetLabelCustom
Set-FileLabel
[-Path] <String[]>
-LabelId <Guid>
-CustomPermissions <AIPCustomPermissions>
[-JustificationMessage <String>]
[-Owner <String>]
[-PreserveFileDetails]
Custom
Set-FileLabel
[-Path] <String[]>
-CustomPermissions <AIPCustomPermissions>
[-Owner <String>]
[-PreserveFileDetails]
SetAutoLabel
Set-FileLabel
[-Path] <String[]>
[-JustificationMessage <String>]
[-Owner <String>]
[-Force]
[-PreserveFileDetails]
[-AutoLabel]
WhatIf
Set-FileLabel
[-Path] <String[]>
[-PreserveFileDetails]
[-WhatIf]
[-DiscoveryInfoTypes <String[]>]
Description
For the Microsoft Purview Information Protection client, the Set-FileLabel cmdlet sets 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-CustomPermissions 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.
Examples
Example 1: Apply the "General" label to all files that do not currently have a label
Get-FileStatus -Path \\Finance\Projects\ |
Where-Object {$_.IsLabeled -eq $False} |
Set-FileLabel -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-FileStatus 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
Get-ChildItem C:\Projects\*.docx -File -Recurse |
Get-FileStatus |
Where-Object {$_.IsLabeled -eq $False} |
Set-FileLabel -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-FileStatus 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-FileStatus.
Example 3: Apply the "General" label to all files in a folder and any of its subfolders
Set-FileLabel -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 C:\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: Apply the "General" label to a single file, which requires justification
$setFileLabelSplat = @{
Path = '\\Finance\Projects\Analysis.xlsx'
LabelId = 'd9f23ae3-1324-1234-1234-f515f824c57b'
JustificationMessage = 'The previous label no longer applies'
}
Set-FileLabel @setFileLabelSplat
FileName Status Comment
-------- ------ ------------
\\finance\projects\analysis.xlsx Success
This command sets the "General" label for a file that is already labeled with a higher sensitivity label. The sensitivity 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: Protect a file with custom permissions
$newCustomPermissionsSplat = @{
Users = '[email protected]', '[email protected]'
Permissions = 'Reviewer'
ExpirationDate = (Get-Date -Month 1 -Day 1 -Year 2020)
}
$permissions = New-CustomPermissions @newCustomPermissionsSplat
Set-FileLabel 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 6: Apply a label and custom permissions to file
$permissions = New-CustomPermissions -Users [email protected], [email protected] -Permissions Reviewer
$setFileLabelSplat = @{
LabelId = 'd9f23ae3-1324-1234-1234-f515f824c57b'
CustomPermissions = $permissions
}
Set-FileLabel @setFileLabelSplat C:\Projects\Analysis.docx
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 7: Scan all files in a folder tree and apply labels according to the configured conditions
Set-FileLabel -AutoLabel -Path C:\Projects\ -PreserveFileDetails
FileName : C:\Projects\Project1.docx
Status : Success
Comment :
MainLabelName : Confidential
MainLabelId : 074e257c-1234-1234-1234-34a182080e71
SubLabelName : Finance group
SubLabelId : d9f23ae3-1234-1234-1234-f515f824c57b
FileName : C:\Projects\Datasheet.pdf
Status : Skipped
Comment : No label to apply
MainLabelName :
MainLabelId :
SubLabelName :
SubLabelId :
FileName : C:\Projects\Analysis.xlsx
Status : Skipped
Comment : No label to apply
MainLabelName :
MainLabelId :
SubLabelName :
SubLabelId :
FileName : C:\Projects\Pricelist.xlsx
Status : Skipped
Comment : No label to apply
MainLabelName :
MainLabelId :
SubLabelName :
SubLabelId :
FileName : C:\Projects\Dashboard.xlsx
Status : Success
Comment :
MainLabelName : Public
MainLabelId : f018e9e7-0cfc-4c69-b27a-ac3cb7df43cc
SubLabelName :
SubLabelId :
This command scans all files in the Projects folder and any of its subfolders, and sets labels
according to the configured conditions in the auto labeling policy. In this example, there are five
files and two files are automatically labeled. The Datasheet.pdf file is not labeled because its
contents does not match the configured conditions for automatic labeling Analysis.xlsx was already
manually labeled, and Pricelist.xlsx has a higher label. Because the command is run without the
Force parameter, the existing labels for Analysis.xlsx and Pricelist.xlsx are not
overwritten.
If the applied labels are also configured to apply Rights Management protection, the files that are successfully labeled with this command are also protected. 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.
Because the PreserveFileDetails parameter is specified, the Date Modified of the labeled files remains unchanged.
Example 8: Scan all files in a folder tree and apply labels according to the configured conditions, overriding any existing labels
Set-FileLabel -Autolabel -Path C:\Projects\ -Force -PreserveFileDetails
FileName : C:\Projects\Project1.docx
Status : Success
Comment :
MainLabelName : Confidential
MainLabelId : 074e257c-1234-1234-1234-34a182080e71
SubLabelName : Finance group
SubLabelId : d9f23ae3-1234-1234-1234-f515f824c57b
FileName : C:\Projects\Datasheet.pdf
Status : Skipped
Comment : No label to apply
MainLabelName :
MainLabelId :
SubLabelName :
SubLabelId :
FileName : C:\Projects\Analysis.xlsx
Status : Success
Comment :
MainLabelName : Public
MainLabelId : f018e9e7-0cfc-4c69-b27a-ac3cb7df43cc
SubLabelName :
SubLabelId :
FileName : C:\Projects\Pricelist.xlsx
Status : Success
Comment :
MainLabelName : Public
MainLabelId : f018e9e7-0cfc-4c69-b27a-ac3cb7df43cc
SubLabelName :
SubLabelId :
FileName : C:\Projects\Dashboard.xlsx
Status : Success
Comment :
MainLabelName : Public
MainLabelId : f018e9e7-0cfc-4c69-b27a-ac3cb7df43cc
SubLabelName :
SubLabelId :
This command is similar to the previous example in that it also scans all files in the Projects
folder and any of its subfolders, and sets labels according to the configured conditions for auto
labeling. However, this time, because the command includes the Force parameter, it also replaces
the existing label for Dashboard.xlsx, and Pricelist.xlsx.
The contents of Datasheet.pdf did not match any configured conditions and this file remains
without a label.
Example 9: Scan a file for all known sensitive information types
Set-FileLabel -AutoLabel -Path C:\Projects\Project1.docx -DiscoveryInfoTypes All
MainLabelName : General
MainLabelId : 89a453df-5df4-4976-8191-jdn2fsf9560a
SubLabelName :
SubLabelId :
WhatIf : True
MatchedInformationTypes : {Credit Card Number, U.S. Social Security Number (SSN), International Classification of
Diseases (ICD-10-CM), International Classification of Diseases (ICD-9-CM)}
LastModifiedBy :
LastModifiedTime : 8/19/2014 5:11:26 AM
FileName : C:\Projects\Project1.docx
Status : Success
Comment :
This command discovers all known information types in Project1.docx file without applying protection or a label.
Example 10: Scan a file for specific sensitive information types
$setFileLabelSplat = @{
AutoLabel = -AutoLabel
Path = 'C:\Projects\Project1.docx'
DiscoveryInfoTypes = "50842eb7-edc8-4019-85dd-5a5c1f2bb085", "a44669fe-0d48-453d-a9b1-2cc83f2cba77"
}
Set-FileLabel @setFileLabelSplat
MainLabelName : General
MainLabelId : 89a453df-5df4-4976-8191-jdn2fsf9560a
SubLabelName :
SubLabelId :
WhatIf : True
MatchedInformationTypes : {Credit Card Number, U.S. Social Security Number (SSN)}
LastModifiedBy :
LastModifiedTime : 8/19/2014 5:11:26 AM
FileName : Project1.docx
Status : Success
Comment :
This command discovers the specific information types of Credit Card Number, and Social
Security Number (SSN) in Project1.docx file without applying protection or a label.
Example 11: Scan a file for specific sensitive information types and display the values found
$setFileLabelSplat = @{
AutoLabel = -AutoLabel
Path = 'C:\Projects\Project1.docx'
DiscoveryInfoTypes = '50842eb7-edc8-4019-85dd-5a5c1f2bb085',
'a44669fe-0d48-453d-a9b1-2cc83f2cba77'
}
$x = Set-FileLabel @setFileLabelSplat
$x.MatchedInformationTypes
RulePackageSetId : 00000000-0000-0000-0000-000000000000
RulePackageId : 00000000-0000-0000-0000-000000000000
RuleId : 50842eb7-edc8-4019-85dd-5a5c1f2bb085
Name : Credit Card Number
Count : 1
UniqueCount : 1
Confidence : 85
SensitiveContents : {Offset: 2089, Length: 19}
RulePackageSetId : 00000000-0000-0000-0000-000000000000
RulePackageId : 00000000-0000-0000-0000-000000000000
RuleId : a44669fe-0d48-453d-a9b1-2cc83f2cba77
Name : U.S. Social Security Number (SSN)
Count : 1
UniqueCount : 1
Confidence : 85
SensitiveContents : {Offset: 7063, Length: 11}
$x.MatchedInformationTypes[0].SensitiveContents | Format-List
Offset : 2089
Length : 19
Value : 4539-9572-7949-2212
Context : OLOGICAL SCIENCES Credit Card #
Expiration Date: 4539-9572-7949-2212
8/2009 Department: BIOLOGICAL SCIENCES Anticipa
Similar to the previous example, the first command discovers the specific information types of
Credit Card Number, and Social Security Number (SSN) in Project1.docx file without
applying protection or a label. However, in this example, the results are stored in a variable for
further processing.
The second command is then used to display the contents of the matched information types, which includes the SensitiveContents parameter.
The final command displays and formats for easier reading the data that's identified by the first sensitive information type, which in this example, is the credit card details.
Parameters
-AutoLabel
When -AutoLabel is used, cmdlet runs in auto-labeling mode. When -AutoLabel cmdlet is not used, runs in manual labeling mode.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
SetAutoLabel
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-CustomPermissions
Specifies the variable name that stores an ad-hoc protection policy, which was created by using the New-CustomPermissions cmdlet. The ad-hoc protection policy is used to protect the file or files with custom permissions.
Parameter properties
| Type: | AIPCustomPermissions |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
SetLabelCustom
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
Custom
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-DiscoveryInfoTypes
Specify the sensitive information types to be discovered when you use the WhatIf parameter.
If you want to search for specific sensitive information types, specify the Entity id number for that information type, which you can find listed in Sensitive information types in Exchange Server.
For example, "50842eb7-edc8-4019-85dd-5a5c1f2bb085" is the number to specify for the Credit Card Number sensitive information type.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
WhatIf
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Force
Replaces an existing label when the configured conditions apply.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
SetAutoLabel
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-JustificationMessage
The justification reason for lowering the classification label, removing a label, or removing protection, if the sensitivity 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".
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
SetLabel
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
SetLabelCustom
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
SetAutoLabel
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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 Purview compliance portal. 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-FileStatus cmdlet to identify the label ID (MainLabelId or SubLabelId).
Parameter properties
| Type: | Guid |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
SetLabel
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
SetLabelCustom
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Owner
Specifies owner for applying label or protection to the file.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
SetLabel
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
SetLabelCustom
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
Custom
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
SetAutoLabel
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | 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 2022
- SharePoint Server 2019
- SharePoint Server 2016
- SharePoint Server 2013
For example:
C:\Folder\C:\Folder\Filename\\Server\Folderhttp://sharepoint.contoso.com/Shared%20Documents/Folder
Paths can include spaces when you enclose the path value with quotes.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | FullName, FileName |
Parameter sets
(All)
| Position: | 0 |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | True |
| Value from remaining arguments: | 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.
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 |
-WhatIf
Shows what would happen if the cmdlet runs. The cmdlet is not run.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
WhatIf
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
Inputs
System.String
Outputs
Microsoft.InformationProtection.Powershell.AIP.Results.SetAIPFileResult
Notes
When running the Set-FileLabel cmdlet in a loop, add the following command after the cmdlet:
[GC]::Collect()[GC]::WaitForPendingFinalizers()
These commands ensure that the garbage collector runs and releases memory that is no longer needed.