EXOSafeLinksPolicy¶

Parameters¶

Parameter	Attribute	DataType	Description	Allowed Values
Identity	Key	String	The Identity parameter specifies the SafeLinks policy that you want to modify.
Ensure	Write	String	Specify if this policy should exist or not.	`Present`, `Absent`
AdminDisplayName	Write	String	The AdminDisplayName parameter specifies a description for the policy.
AllowClickThrough	Write	Boolean	The AllowClickThrough parameter specifies whether to allow users to click through to the original URL on warning pages.
CustomNotificationText	Write	String	The custom notification text specifies the customized notification text to show to users.
DeliverMessageAfterScan	Write	Boolean	The DeliverMessageAfterScan parameter specifies whether to deliver email messages only after Safe Links scanning is complete. Valid values are: $true: Wait until Safe Links scanning is complete before delivering the message. $false: If Safe Links scanning can't complete, deliver the message anyway. This is the default value.
DoNotRewriteUrls	Write	StringArray[]	The DoNotRewriteUrls parameter specifies a URL that's skipped by Safe Links scanning. You can specify multiple values separated by commas.
EnableForInternalSenders	Write	Boolean	The EnableForInternalSenders parameter specifies whether the Safe Links policy is applied to messages sent between internal senders and internal recipients within the same Exchange Online organization.
EnableOrganizationBranding	Write	Boolean	The EnableOrganizationBranding parameter specifies whether your organization's logo is displayed on Safe Links warning and notification pages.
EnableSafeLinksForOffice	Write	Boolean	The EnableSafeLinksForOffice parameter specifies whether to enable Safe Links protection for supported Office desktop, mobile, or web apps.
EnableSafeLinksForTeams	Write	Boolean	The EnableSafeLinksForTeams parameter specifies whether Safe Links is enabled for Microsoft Teams. Valid values are: $true: Safe Links is enabled for Teams. If a protected user clicks a malicious link in a Teams conversation, group chat, or from channels, a warning page will appear in the default web browser. $false: Safe Links isn't enabled for Teams. This is the default value.
EnableSafeLinksForEmail	Write	Boolean	The EnableSafeLinksForEmail parameter specifies whether to enable Safe Links protection for email messages. Valid values are: $true: Safe Links is enabled for email. When a user clicks a link in an email, the link is checked by Safe Links. If the link is found to be malicious, a warning page appears in the default web browser. $false: Safe Links isn't enabled for email. This is the default value.
DisableUrlRewrite	Write	Boolean	The DisableUrlRewrite parameter specifies whether to rewrite (wrap) URLs in email messages. Valid values are: $true: URLs in messages are not rewritten, but messages are still scanned by Safe Links prior to delivery. Time of click checks on links are done using the Safe Links API in supported Outlook clients (currently, Outlook for Windows and Outlook for Mac). Typically, we don't recommend using this value. $false: URLs in messages are rewritten. API checks still occur on unwrapped URLs in supported clients if the user is in a valid Safe Links policy. This is the default value.
ScanUrls	Write	Boolean	The ScanUrls parameter specifies whether to enable or disable the scanning of links in email messages. Valid values are: $true: Scanning links in email messages is enabled. $false: Scanning links in email messages is disabled. This is the default value.
TrackClicks	Write	Boolean	The TrackClicks parameter specifies whether to track user clicks related to Safe Links protection of links.
UseTranslatedNotificationText	Write	Boolean	The UseTranslatedNotificationText specifies whether to use Microsoft Translator to automatically localize the custom notification text that you specified with the CustomNotificationText parameter.
Credential	Write	PSCredential	Credentials of the Exchange Global Admin
ApplicationId	Write	String	Id of the Azure Active Directory application to authenticate with.
TenantId	Write	String	Id of the Azure Active Directory tenant used for authentication.
CertificateThumbprint	Write	String	Thumbprint of the Azure Active Directory application's authentication certificate to use for authentication.
CertificatePassword	Write	PSCredential	Username can be made up to anything but password will be used for CertificatePassword
CertificatePath	Write	String	Path to certificate used in service principal usually a PFX file.
ManagedIdentity	Write	Boolean	Managed ID being used for authentication.
AccessTokens	Write	StringArray[]	Access token used for authentication.

Description¶

This resource configures the settings of the SafeLinks policies in your cloud-based organization.

Permissions¶

Exchange¶

To authenticate with Microsoft Exchange, this resource required the following permissions:

Roles¶

Transport Hygiene, Security Admin, View-Only Configuration, Security Reader

Role Groups¶

Organization Management

Examples¶

Example 1¶

This example is used to test new resources and showcase the usage of new resources being worked on. It is not meant to use as a production baseline.

Configuration Example
{
    param(
        [Parameter()]
        [System.String]
        $ApplicationId,

        [Parameter()]
        [System.String]
        $TenantId,

        [Parameter()]
        [System.String]
        $CertificateThumbprint
    )
    Import-DscResource -ModuleName Microsoft365DSC

    node localhost
    {
        EXOSafeLinksPolicy 'ConfigureSafeLinksPolicy'
        {
            Identity                      = 'Marketing Block URL'
            AdminDisplayName              = 'Marketing Block URL'
            CustomNotificationText        = 'Blocked URLs for Marketing'
            DeliverMessageAfterScan       = $True
            EnableOrganizationBranding    = $True
            EnableSafeLinksForTeams       = $True
            ScanUrls                      = $True
            Ensure                        = 'Present'
            ApplicationId         = $ApplicationId
            TenantId              = $TenantId
            CertificateThumbprint = $CertificateThumbprint
        }
    }
}

Example 2¶

This example is used to test new resources and showcase the usage of new resources being worked on. It is not meant to use as a production baseline.

Configuration Example
{
    param(
        [Parameter()]
        [System.String]
        $ApplicationId,

        [Parameter()]
        [System.String]
        $TenantId,

        [Parameter()]
        [System.String]
        $CertificateThumbprint
    )
    Import-DscResource -ModuleName Microsoft365DSC

    node localhost
    {
        EXOSafeLinksPolicy 'ConfigureSafeLinksPolicy'
        {
            Identity                      = 'Marketing Block URL'
            AdminDisplayName              = 'Marketing Block URL'
            CustomNotificationText        = 'Blocked URLs for Marketing'
            DeliverMessageAfterScan       = $True
            EnableOrganizationBranding    = $False # Updated Property
            EnableSafeLinksForTeams       = $True
            ScanUrls                      = $True
            Ensure                        = 'Present'
            ApplicationId         = $ApplicationId
            TenantId              = $TenantId
            CertificateThumbprint = $CertificateThumbprint
        }
    }
}

Example 3¶

This example is used to test new resources and showcase the usage of new resources being worked on. It is not meant to use as a production baseline.

Configuration Example
{
    param(
        [Parameter()]
        [System.String]
        $ApplicationId,

        [Parameter()]
        [System.String]
        $TenantId,

        [Parameter()]
        [System.String]
        $CertificateThumbprint
    )
    Import-DscResource -ModuleName Microsoft365DSC

    node localhost
    {
        EXOSafeLinksPolicy 'ConfigureSafeLinksPolicy'
        {
            Identity                      = 'Marketing Block URL'
            Ensure                        = 'Absent'
            ApplicationId         = $ApplicationId
            TenantId              = $TenantId
            CertificateThumbprint = $CertificateThumbprint
        }
    }
}