Create Safe Links policies using PowerShell

  • 9 minutes

Organizations can use Exchange Online PowerShell or standalone EOP PowerShell to separately manage Safe Links policies and rules. A Safe Links policy consists of a Safe Links policy and a Safe Links rule.

When you use PowerShell cmdlets:

  • A rule defines the conditions.
  • A policy defines the actions to take after the organization meets the conditions within the rule.

The conditions and exceptions make up a rule that becomes part of that policy. The policy dictates the action to take. It also dictates the redirect settings. Organizations can change rules independently of the policies to which they belong.

Important

When using PowerShell to create a policy, you must create the policy before the rule. You must create the policy first so that you can later assign it to the rule. If you create the rule first, you won't have a policy to assign to it.

In PowerShell, the difference between Safe Links policies and Safe Links rules is clear. You manage Safe Links policies by using the *-SafeLinksPolicy cmdlets, and you manage Safe Links rules by using the *-SafeLinksRule cmdlets.

  • In PowerShell, you create the Safe Links policy first, then you create the Safe Links rule that identifies the policy that the rule applies to.
  • In PowerShell, you modify the settings in the Safe Links policy and the Safe Links rule separately.
  • When you remove a Safe Links policy from PowerShell, the system doesn't automatically remove the corresponding Safe Links rule, and vice versa.

The following table identifies EOP cmdlets that you can use to create and manage Safe Links rules and policies. For more details about any of the Safe Links cmdlets, select the hyperlink associated with a cmdlet in the table.

If you want to do this task: Use this cmdlet:
View your Safe Links policy settings. Get-SafeLinksPolicy
Edit an existing Safe Links policy. Set-SafeLinksPolicy
Create a new custom Safe Links policy. New-SafeLinksPolicy
Remove a custom Safe Links policy. Remove-SafeLinksPolicy
View your Safe Links rule settings. Get-SafeLinksRule
Edit an existing Safe Links rule. Set-SafeLinksRule
Create a new custom Safe Links rule. New-SafeLinksRule
Remove a custom Safe Links rule. Remove-SafeLinksRule

Creating a Safe Links policy in PowerShell is a two-step process:

  1. Create the Safe Links policy.
  2. Create the Safe Links rule that specifies the Safe Links policy the rule applies to.

You can create a new Safe Links rule and assign an existing, unassociated Safe Links policy to it. You can't associate a Safe Links rule with more than one Safe Links policy.

You can configure the following settings on new Safe Links policies in PowerShell that aren't available in the Microsoft Defender portal until after you create the policy:

  • Create the new policy as disabled (Enabled $false on the New-SafeLinksRule cmdlet).
  • Set the priority of the policy during creation (Priority <Number>) on the New-SafeLinksRule cmdlet).

A new Safe Links policy that you create in PowerShell isn't visible in the Microsoft Defender portal until you assign the policy to a Safe Links rule.

Step 1 - Create a Safe Links policy using PowerShell

You should use the following PowerShell syntax to create a Safe Links policy:

New-SafeLinksPolicy -Name "<PolicyName>" [-AdminDisplayName "<Comments>"] [-IsEnabled <$true | $false>] [-EnableSafeLinksForTeams <$true | $false>] [-ScanUrls <$true | $false>] [-DeliverMessageAfterScan <$true | $false>] [-EnableForInternalSenders <$true | $false>] [-DoNotAllowClickThrough <$true | $false>] [-DoNotTrackUserClicks <$true | $false>] [-DoNotRewriteUrls "Entry1","Entry2",..."EntryN"]

The following example creates a Safe Links policy named Contoso All with the following values:

  • Turn on URL scanning and rewriting in email messages.
  • Turn on URL scanning in Teams (TAP Preview only).
  • Turn on real-time scanning of selected URLs, including selected links that point to files.
  • Wait for URL scanning to complete before delivering the message.
  • Turn on URL scanning and rewriting for internal messages.
  • Track user selections related to Safe Links protection. This example doesn't use the DoNotTrackUserClicks parameter. Since the default value of this parameter is $false, the system tracks user selections.
  • Don't allow users to select through to the original URL.
New-SafeLinksPolicy -Name "Contoso All" -IsEnabled $true -EnableSafeLinksForTeams $true -ScanUrls $true -DeliverMessageAfterScan $true -EnableForInternalSenders $true -DoNotAllowClickThrough $true

Step 2 - Create a Safe Links rule using PowerShell

You should use the following PowerShell syntax to create a Safe Links rule:

New-SafeLinksRule -Name "<RuleName>" -SafeLinksPolicy "<PolicyName>" <Recipient filters> [<Recipient filter exceptions>] [-Comments "<OptionalComments>"] [-Enabled <$true | $false>]

The following example creates a Safe Links rule named Contoso All with the following conditions:

  • Associate the rule with the Safe Links policy named Contoso All.
  • Apply the rule to all recipients in the contoso.com domain.
  • Apply the default priority. This example doesn't use the Priority parameter, so Safe Links uses the default priority instead.
  • Enable the rule. This example doesn't use the Enabled parameter. Since the default value of this parameter is $true, the Safe Links service automatically enables the rule.
New-SafeLinksRule -Name "Contoso All" -SafeLinksPolicy "Contoso All" -RecipientDomainIs contoso.com

The highest priority value you can set on a rule is 0. The lowest value you can set depends on the number of rules. For example, if you have five rules, you can use the priority values 0 through 4.

Changing the priority of an existing rule can have a cascading effect on other rules. For example, if you have five custom rules (priorities 0 through 4) and you change the priority of a rule to 2. What happens? The system automatically changes:

  • the rule with priority 2 to priority 3.
  • the rule with priority 3 to priority 4.

To set the priority of a Safe Links rule in PowerShell, use the following syntax:

Set-SafeLinksRule -Identity "<RuleName>" -Priority <Number>

The following example sets the priority of the rule named Marketing Department to 2. The system automatically decreases by 1 the priority of all existing rules that have a priority less than or equal to 2.

Set-SafeLinksRule -Identity "Marketing Department" -Priority 2

Tip

To set the priority of a new rule when you create it, use the Priority parameter on the New-SafeLinksRule cmdlet instead.

Knowledge check

Choose the best response for the following question. Then select “Check your answers.”

Check your knowledge

1.

As the Microsoft 365 Administrator for Contoso, Holly Dickson created a Safe Links policy using Exchange Online PowerShell. After Holly navigated to the Safe Links page in the Microsoft Defender portal, she couldn't find the Safe Links policy. What prevented the Safe Links policy that Holly created in PowerShell from appearing in the Microsoft Defender portal?