New-UnifiedAuditLogRetentionPolicy
This cmdlet is available only in Security & Compliance PowerShell. For more information, see Security & Compliance PowerShell.
Use the New-UnifiedAuditLogRetentionPolicy cmdlet to create audit log retention policies in the Microsoft Defender portal or the Microsoft Purview compliance portal.
For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.
Syntax
Default (Default)
New-UnifiedAuditLogRetentionPolicy
[-Name] <String>
-Priority <Int32>
-RetentionDuration <UnifiedAuditLogRetentionDuration>
[-Confirm]
[-Description <String>]
[-Operations <MultiValuedProperty>]
[-RecordTypes <MultiValuedProperty>]
[-UserIds <MultiValuedProperty>]
[-WhatIf]
[<CommonParameters>]
Description
Audit log retention policies are used to specify a retention duration for audit logs for that are generated by admin and user activity. An audit log retention policy can specify the retention duration based on the type of audited activities, the Microsoft 365 service that activities are performed in, or the users who performed the activities. For more information, see Manage audit log retention policies.
To use this cmdlet in Security & Compliance PowerShell, you need to be assigned permissions. For more information, see Permissions in the Microsoft Defender portal or Permissions in the Microsoft Purview compliance portal.
Examples
Example 1
New-UnifiedAuditLogRetentionPolicy -Name "Microsoft Teams Audit Policy" -Description "One year retention policy for all Microsoft Teams activities" -RecordTypes MicrosoftTeams -RetentionDuration TwelveMonths -Priority 100
This example creates an audit log retention policy that retains all audit logs related to Microsoft Teams events for one year.
Example 2
New-UnifiedAuditLogRetentionPolicy -Name "SearchQueryPerformed by app@sharepoint" -Description "90 day retention policy for noisy SharePoint events" -RecordTypes SharePoint -Operations SearchQueryPerformed -UserIds "app@sharepoint" -RetentionDuration ThreeMonths -Priority 10000
This example creates an audit log retention policy that retains all audit logs for the SearchQueryPerformed activity performed by the app@sharepoint service account for 90 days.
Parameters
-Confirm
Applicable: Security & Compliance
The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.
- Destructive cmdlets (for example, Remove-* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax:
-Confirm:$false. - Most other cmdlets (for example, New-* and Set-* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| 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 |
-Description
Applicable: Security & Compliance
The Description parameter specifies a description for the audit log retention policy. The maximum length is 256 characters. If the value contains spaces, enclose the value in quotation marks (").
Parameter properties
| Type: | String |
| 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 |
-Name
Applicable: Security & Compliance
The Name parameter specifies a unique name for the audit log retention policy. The maximum length is 64 characters. If the value contains spaces, enclose the value in quotation marks (").
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 0 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Operations
Applicable: Security & Compliance
The Operations parameter specifies the audit log operations that are retained by the policy. For a list of the available values for this parameter, see Audited activities.
You can enter multiple values separated by commas. If the values contain spaces or otherwise require quotation marks, use the following syntax: "Value1","Value2",..."ValueN".
If you use this parameter, you must also use the RecordTypes parameter to specify the record type. You can't use this parameter if you've specified more than one value for the RecordTypes parameter.
Parameter properties
| Type: | MultiValuedProperty |
| 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 |
-Priority
Applicable: Security & Compliance
The Priority parameter specifies a priority value for the policy that determines the order of policy processing. A higher integer value indicates a lower priority. The value 1 is the highest priority, and the value 10000 is the lowest priority. No two policies can have the same priority value.
This parameter is required when you create an audit log retention policy, and you must use a unique priority value.
Any custom audit log retention policy that you create take precedence over the default audit log retention policy. For more information, see Manage audit log retention policies.
Parameter properties
| Type: | Int32 |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-RecordTypes
Applicable: Security & Compliance
The RecordTypes parameter specifies the audit logs of a specific record type that are retained by the policy. For details about the available values, see AuditLogRecordType.
You can specify multiple values separated by commas. If you specify more than one value, you can't use the Operations parameter.
Parameter properties
| Type: | MultiValuedProperty |
| 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 |
-RetentionDuration
Applicable: Security & Compliance
The RetentionDuration parameter specifies how long audit log records are kept. Valid values are:
- ThreeMonths
- SixMonths
- NineMonths
- TwelveMonths
- TenYears
Parameter properties
| Type: | UnifiedAuditLogRetentionDuration |
| Default value: | None |
| Accepted values: | ThreeMonths, SixMonths, NineMonths, TwelveMonths, TenYears |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-UserIds
Applicable: Security & Compliance
The UserIds parameter specifies the audit logs that are retained by the policy based on the ID of the user who performed the action.
You can enter multiple values separated by commas. If the values contain spaces or otherwise require quotation marks, use the following syntax: "Value1","Value2",..."ValueN".
Parameter properties
| Type: | MultiValuedProperty |
| 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
Applicable: Security & Compliance
The WhatIf switch doesn't work in Security & Compliance PowerShell.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| 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.