SqlDatabaseMail: Add parameter UseDefaultCredentials (#2001)

- SqlDatabaseMail
  - Added the parameter `UseDefaultCredentials` to control use of the DatabaseEngine
    service account for SMTP server authentication.

Author: RandyInMarin

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - SqlServerDsc
   - Added build tasks to generate Wiki documentation for public commands.
+- SqlDatabaseMail
+  - Added the parameter `UseDefaultCredentials` to control use of the DatabaseEngine
+    service account for SMTP server authentication.
 
 ### Fixed
 

source/DSCResources/DSC_SqlDatabaseMail/DSC_SqlDatabaseMail.psm1

@@ -64,18 +64,19 @@ function Get-TargetResource
     )
 
     $returnValue = @{
-        Ensure         = 'Absent'
-        ServerName     = $ServerName
-        InstanceName   = $InstanceName
-        AccountName    = $null
-        EmailAddress   = $null
-        MailServerName = $null
-        LoggingLevel   = $null
-        ProfileName    = $null
-        DisplayName    = $null
-        ReplyToAddress = $null
-        Description    = $null
-        TcpPort        = $null
+        Ensure                = 'Absent'
+        ServerName            = $ServerName
+        InstanceName          = $InstanceName
+        AccountName           = $null
+        EmailAddress          = $null
+        MailServerName        = $null
+        LoggingLevel          = $null
+        ProfileName           = $null
+        DisplayName           = $null
+        ReplyToAddress        = $null
+        Description           = $null
+        TcpPort               = $null
+        UseDefaultCredentials = $null
     }
 
     Write-Verbose -Message (
@@ -145,6 +146,7 @@ function Get-TargetResource
                 {
                     $returnValue['MailServerName'] = $mailServer.Name
                     $returnValue['TcpPort'] = $mailServer.Port
+                    $returnValue['UseDefaultCredentials'] = $mailServer.UseDefaultCredentials
                 }
 
                 $mailProfile = $databaseMail.Profiles |
@@ -233,10 +235,19 @@ function Get-TargetResource
     .PARAMETER TcpPort
         The TCP port used for communication. Default value is port 25.
 
+    .PARAMETER UseDefaultCredentials
+        Controls use of the DatabaseEngine service account for SMTP server authentication.
+        If $true, the DatabaseEngine service account is used access the SMTP server.
+        If $false, DatabaseEngine service account is not used.
+
     .NOTES
         Information about the different properties can be found here
         https://docs.microsoft.com/en-us/sql/relational-databases/database-mail/configure-database-mail.
 
+        "UseDefaultCredentials" corresponds to "Windows Authentication using Database Engine service credentials"
+        described at the above link.  This dsc resource does not yet address setting state for basic or anonymous
+        SMTP access that's used when UseDefaultCredentials is false.
+
 #>
 function Set-TargetResource
 {
@@ -293,7 +304,11 @@ function Set-TargetResource
 
         [Parameter()]
         [System.UInt16]
-        $TcpPort = 25
+        $TcpPort = 25,
+
+        [Parameter()]
+        [System.Boolean]
+        $UseDefaultCredentials
     )
 
     Write-Verbose -Message (
@@ -382,6 +397,11 @@ function Set-TargetResource
                             $mailServer.Port = $TcpPort
                         }
 
+                        if ($PSBoundParameters.ContainsKey('UseDefaultCredentials'))
+                        {
+                            $mailServer.UseDefaultCredentials = $UseDefaultCredentials
+                        }
+
                         $mailServer.Alter()
                     }
                 }
@@ -483,6 +503,21 @@ function Set-TargetResource
                         $mailServer.Port = $TcpPort
                         $mailServer.Alter()
                     }
+
+                    $currentUseDefaultCredentials = $mailServer.UseDefaultCredentials
+                    if ($PSBoundParameters.ContainsKey('UseDefaultCredentials') -and $currentUseDefaultCredentials -ne $UseDefaultCredentials)
+                    {
+                        Write-Verbose -Message (
+                            $script:localizedData.UpdatingPropertyOfMailServer -f @(
+                                $currentUseDefaultCredentials
+                                $UseDefaultCredentials
+                                $script:localizedData.MailServerPropertyUseDefaultCredentials
+                            )
+                        )
+
+                        $mailServer.UseDefaultCredentials = $UseDefaultCredentials
+                        $mailServer.Alter()
+                    }
                 }
 
                 $databaseMailProfile = $databaseMail.Profiles | Where-Object -FilterScript {
@@ -633,6 +668,11 @@ function Set-TargetResource
 
     .PARAMETER TcpPort
         The TCP port used for communication. Default value is port 25.
+
+    .PARAMETER UseDefaultCredentials
+        Controls use of the DatabaseEngine service account for SMTP server authentication.
+        If $true, the DatabaseEngine service account is used access the SMTP server.
+        If $false, DatabaseEngine service account is not used.
 #>
 function Test-TargetResource
 {
@@ -691,7 +731,11 @@ function Test-TargetResource
 
         [Parameter()]
         [System.UInt16]
-        $TcpPort = 25
+        $TcpPort = 25,
+
+        [Parameter()]
+        [System.Boolean]
+        $UseDefaultCredentials
     )
 
     $getTargetResourceParameters = @{
@@ -727,6 +771,7 @@ function Test-TargetResource
                 'DisplayName'
                 'Description'
                 'LoggingLevel'
+                'UseDefaultCredentials'
             )
             TurnOffTypeChecking = $true
             Verbose             = $VerbosePreference

source/DSCResources/DSC_SqlDatabaseMail/DSC_SqlDatabaseMail.schema.mof

@@ -13,4 +13,5 @@ class DSC_SqlDatabaseMail : OMI_BaseResource
     [Write, Description("The description for the _Database Mail_ profile and account.")] String Description;
     [Write, Description("The logging level that the _Database Mail_ will use. If not specified the default logging level is `'Extended'`."), ValueMap{"Normal","Extended","Verbose"}, Values{"Normal","Extended","Verbose"}] String LoggingLevel;
     [Write, Description("The TCP port used for communication. Default value is port `25`.")] UInt16 TcpPort;
+    [Write, Description("Specifies if the DatabaseEngine credentials are used for SMTP server authentication.")] Boolean UseDefaultCredentials;
 };

source/DSCResources/DSC_SqlDatabaseMail/en-US/DSC_SqlDatabaseMail.strings.psd1

@@ -22,6 +22,7 @@ ConvertFrom-StringData @'
     MailServerPropertyReplyToEmailAddress = reply to e-mail address
     MailServerPropertyServerName = server name
     MailServerPropertyTcpPort = TCP port
+    MailServerPropertyUseDefaultCredentials = Use default credentials
     CreatingMailProfile = Creating a public default profile '{0}'.
     MailProfileExist = The public default profile '{0}' already exist.
     ConfigureSqlAgent = Configure the SQL Agent to use Database Mail.