Add service account management for Reporting Services

CHANGELOG.md

@@ -189,6 +189,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   for SQL Server Reporting Services or Power BI Report Server. Supports waiting
   for dependent services, configurable wait time, and accepts pipeline input
   from `Get-SqlDscRSConfiguration`.
+- Added public commands `Get-SqlDscRSServiceAccount` and
+  `Set-SqlDscRSServiceAccount` to get and set the Windows service account for
+  SQL Server Reporting Services or Power BI Report Server. `Set-SqlDscRSServiceAccount`
+  wraps the `SetWindowsServiceIdentity` CIM method and supports updating encryption
+  key backups.
 - Added public command `Test-SqlDscRSInitialized` to test whether a Reporting
   Services instance is initialized by checking the `IsInitialized` property of
   the configuration CIM instance
@@ -254,6 +259,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     of the deprecated private function `Get-ProtocolNameProperties`
 - `Class-Based Dsc Resource Tests`
   - Updated tests for ResourceBase 2.0.
+- `Set-SqlDscRSUrlReservation`
+  - Added separate parameter set `Recreate` with the parameter `RecreateExisting`
+    to remove and re-add all existing URL reservations for all applications.
+    This is useful after changing the Windows service account, as URL reservations
+    are tied to a specific service account and must be recreated to use the new
+    account. The `Recreate` parameter set does not require `Application` or
+    `UrlString` parameters.
+- Prerequisites Integration Tests
+  - Added `svc-RS` local Windows user for Reporting Services service account
+    integration testing.
 
 ### Fixed
 

azure-pipelines.yml

@@ -558,6 +558,11 @@ stages:
                   'tests/Integration/Commands/Initialize-SqlDscRS.Integration.Tests.ps1'
                   # Group 5 - Post-initialization validation
                   'tests/Integration/Commands/Post.Initialization.RS.Integration.Tests.ps1'
+                  # Group 6 - Service account change
+                  'tests/Integration/Commands/Set-SqlDscRSServiceAccount.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Get-SqlDscRSServiceAccount.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Post.UrlReservationRecreate.RS.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Post.ServiceAccountChange.RS.Integration.Tests.ps1'
                   # Group 8
                   'tests/Integration/Commands/Repair-SqlDscReportingService.Integration.Tests.ps1'
                   'tests/Integration/Commands/Remove-SqlDscRSUrlReservation.Integration.Tests.ps1'
@@ -643,6 +648,11 @@ stages:
                   'tests/Integration/Commands/Initialize-SqlDscRS.Integration.Tests.ps1'
                   # Group 5 - Post-initialization validation
                   'tests/Integration/Commands/Post.Initialization.RS.Integration.Tests.ps1'
+                  # Group 6 - Service account change
+                  'tests/Integration/Commands/Set-SqlDscRSServiceAccount.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Get-SqlDscRSServiceAccount.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Post.UrlReservationRecreate.RS.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Post.ServiceAccountChange.RS.Integration.Tests.ps1'
                   # Group 8
                   'tests/Integration/Commands/Repair-SqlDscPowerBIReportServer.Integration.Tests.ps1'
                   'tests/Integration/Commands/Remove-SqlDscRSUrlReservation.Integration.Tests.ps1'

source/Public/Get-SqlDscRSConfiguration.ps1

@@ -9,9 +9,12 @@
         Reporting Services configuration, such as `Enable-SqlDscRsSecureConnection`
         and `Disable-SqlDscRsSecureConnection`.
 
-        The configuration CIM instance provides access to properties like
-        `SecureConnectionLevel`, `DatabaseServerName`, `VirtualDirectoryReportServer`,
-        and methods for managing Reporting Services configuration.
+        The returned CIM instance provides access to properties documented in
+        [MSReportServer_ConfigurationSetting](https://learn.microsoft.com/en-us/sql/reporting-services/wmi-provider-library-reference/msreportserver-configurationsetting-properties),
+        such as `SecureConnectionLevel`, `DatabaseServerName`,
+        `VirtualDirectoryReportServer`, `WindowsServiceIdentityActual`,
+        'WindowsServiceIdentityConfigured' and methods for managing Reporting
+        Services configuration.
 
     .PARAMETER InstanceName
         Specifies the name of the Reporting Services instance. This is a

source/Public/Get-SqlDscRSServiceAccount.ps1

@@ -0,0 +1,71 @@
+<#
+    .SYNOPSIS
+        Gets the service account for SQL Server Reporting Services.
+
+    .DESCRIPTION
+        Gets the Windows service account for SQL Server Reporting Services or
+        Power BI Report Server from the `MSReportServer_ConfigurationSetting`
+        CIM instance.
+
+        This command returns the current service account name that is being
+        used by the Reporting Services Windows service.
+
+        The configuration CIM instance can be obtained using the
+        `Get-SqlDscRSConfiguration` command and passed via the pipeline.
+
+    .PARAMETER Configuration
+        Specifies the `MSReportServer_ConfigurationSetting` CIM instance for
+        the Reporting Services instance. This can be obtained using the
+        `Get-SqlDscRSConfiguration` command. This parameter accepts pipeline
+        input.
+
+    .EXAMPLE
+        Get-SqlDscRSConfiguration -InstanceName 'SSRS' | Get-SqlDscRSServiceAccount
+
+        Gets the service account for the Reporting Services instance 'SSRS'.
+
+    .EXAMPLE
+        $config = Get-SqlDscRSConfiguration -InstanceName 'SSRS'
+        Get-SqlDscRSServiceAccount -Configuration $config
+
+        Gets the service account using a stored configuration object.
+
+    .INPUTS
+        `Microsoft.Management.Infrastructure.CimInstance`
+
+        Accepts MSReportServer_ConfigurationSetting CIM instance via pipeline.
+
+    .OUTPUTS
+        `System.String`
+
+        Returns the service account name.
+
+    .NOTES
+        This is a convenience wrapper around accessing the
+        `WindowsServiceIdentityActual` property of the configuration CIM
+        instance.
+
+    .LINK
+        https://docs.microsoft.com/en-us/sql/reporting-services/wmi-provider-library-reference/msreportserver-configurationsetting-properties
+#>
+function Get-SqlDscRSServiceAccount
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the examples use pipeline input the rule cannot validate.')]
+    [CmdletBinding()]
+    [OutputType([System.String])]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [System.Object]
+        $Configuration
+    )
+
+    process
+    {
+        $instanceName = $Configuration.InstanceName
+
+        Write-Verbose -Message ($script:localizedData.Get_SqlDscRSServiceAccount_Getting -f $instanceName)
+
+        return $Configuration.WindowsServiceIdentityActual
+    }
+}

source/Public/Set-SqlDscRSServiceAccount.ps1

@@ -0,0 +1,213 @@
+<#
+    .SYNOPSIS
+        Sets the service account for SQL Server Reporting Services.
+
+    .DESCRIPTION
+        Sets the Windows service account for SQL Server Reporting Services or
+        Power BI Report Server by calling the `SetWindowsServiceIdentity`
+        method on the `MSReportServer_ConfigurationSetting` CIM instance.
+
+        This command changes the Windows service account that the Reporting
+        Services service runs under. Sets file permissions on files and folders
+        in the report server installation directory. The account requires
+        LogonAsService rights in Windows, the specified account will be granted
+        this right.
+
+        The configuration CIM instance can be obtained using the
+        `Get-SqlDscRSConfiguration` command and passed via the pipeline.
+
+    .PARAMETER Configuration
+        Specifies the `MSReportServer_ConfigurationSetting` CIM instance for
+        the Reporting Services instance. This can be obtained using the
+        `Get-SqlDscRSConfiguration` command. This parameter accepts pipeline
+        input.
+
+    .PARAMETER Credential
+        Specifies the credentials for the new service account. The username
+        should be in the format 'DOMAIN\Username' for domain accounts or
+        'Username' for local accounts.
+
+    .PARAMETER UseBuiltInAccount
+        Indicates that the account specified is a built-in Windows account
+        such as 'NT AUTHORITY\NetworkService' or 'NT AUTHORITY\LocalSystem'.
+        When this switch is used, only the username portion of the Credential
+        is used and the password is ignored.
+
+    .PARAMETER RestartService
+        If specified, restarts the Reporting Services service after changing
+        the service account. The service must be restarted for the change to
+        take effect.
+
+    .PARAMETER PassThru
+        If specified, returns the configuration CIM instance after setting
+        the service account.
+
+    .PARAMETER Force
+        If specified, suppresses the confirmation prompt.
+
+    .PARAMETER SuppressUrlReservationWarning
+        If specified, suppresses the warning message about URL reservations
+        needing to be updated when the service account changes.
+
+    .EXAMPLE
+        $credential = Get-Credential
+        Get-SqlDscRSConfiguration -InstanceName 'SSRS' | Set-SqlDscRSServiceAccount -Credential $credential -RestartService
+
+        Sets the service account for Reporting Services and restarts the service.
+
+    .EXAMPLE
+        $credential = New-Object System.Management.Automation.PSCredential('NT AUTHORITY\NetworkService', (New-Object System.Security.SecureString))
+        Get-SqlDscRSConfiguration -InstanceName 'SSRS' | Set-SqlDscRSServiceAccount -Credential $credential -UseBuiltInAccount -Force
+
+        Sets the service account to NetworkService without confirmation.
+
+    .EXAMPLE
+        $credential = Get-Credential
+        Get-SqlDscRSConfiguration -InstanceName 'SSRS' | Set-SqlDscRSServiceAccount -Credential $credential -PassThru
+
+        Sets the service account and returns the configuration CIM instance.
+
+    .INPUTS
+        `Microsoft.Management.Infrastructure.CimInstance`
+
+        Accepts MSReportServer_ConfigurationSetting CIM instance via pipeline.
+
+    .OUTPUTS
+        None. By default, this command does not generate any output.
+
+    .OUTPUTS
+        `Microsoft.Management.Infrastructure.CimInstance`
+
+        When PassThru is specified, returns the MSReportServer_ConfigurationSetting
+        CIM instance.
+
+    .NOTES
+        The Reporting Services service must be restarted for the change to take
+        effect. Use the -RestartService parameter or manually restart the service.
+
+        URL reservations are created for the current service account.
+        Changing the service account requires updating all URL
+        reservations.
+
+    .LINK
+        https://docs.microsoft.com/en-us/sql/reporting-services/wmi-provider-library-reference/configurationsetting-method-setwindowsserviceidentity
+#>
+function Set-SqlDscRSServiceAccount
+{
+    [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the examples use pipeline input the rule cannot validate.')]
+    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
+    [OutputType([System.Object])]
+    param
+    (
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [System.Object]
+        $Configuration,
+
+        [Parameter(Mandatory = $true)]
+        [System.Management.Automation.PSCredential]
+        $Credential,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $UseBuiltInAccount,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $RestartService,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $PassThru,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $Force,
+
+        [Parameter()]
+        [System.Management.Automation.SwitchParameter]
+        $SuppressUrlReservationWarning
+    )
+
+    process
+    {
+        if ($Force.IsPresent -and -not $Confirm)
+        {
+            $ConfirmPreference = 'None'
+        }
+
+        $instanceName = $Configuration.InstanceName
+        $serviceName = $Configuration.ServiceName
+
+        $userName = $Credential.UserName
+
+        Write-Verbose -Message ($script:localizedData.Set_SqlDscRSServiceAccount_Setting -f $userName, $instanceName)
+
+        $descriptionMessage = $script:localizedData.Set_SqlDscRSServiceAccount_ShouldProcessDescription -f $userName, $instanceName
+        $confirmationMessage = $script:localizedData.Set_SqlDscRSServiceAccount_ShouldProcessConfirmation -f $userName
+        $captionMessage = $script:localizedData.Set_SqlDscRSServiceAccount_ShouldProcessCaption
+
+        if ($PSCmdlet.ShouldProcess($descriptionMessage, $confirmationMessage, $captionMessage))
+        {
+            $passwordPlainText = ''
+
+            if (-not $UseBuiltInAccount.IsPresent)
+            {
+                $passwordBstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($Credential.Password)
+
+                try
+                {
+                    $passwordPlainText = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($passwordBstr)
+                }
+                finally
+                {
+                    [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($passwordBstr)
+                }
+            }
+
+            $invokeRsCimMethodParameters = @{
+                CimInstance = $Configuration
+                MethodName  = 'SetWindowsServiceIdentity'
+                Arguments   = @{
+                    UseBuiltInAccount = $UseBuiltInAccount.IsPresent
+                    Account           = $userName
+                    Password          = $passwordPlainText
+                }
+            }
+
+            $currentServiceAccount = $Configuration.WindowsServiceIdentityActual
+
+            try
+            {
+                $null = Invoke-RsCimMethod @invokeRsCimMethodParameters -ErrorAction 'Stop'
+
+                if (-not $SuppressUrlReservationWarning.IsPresent -and $currentServiceAccount -ne $userName)
+                {
+                    Write-Warning -Message ($script:localizedData.Set_SqlDscRSServiceAccount_UrlReservationWarning -f $currentServiceAccount, $userName)
+                }
+
+                if ($RestartService.IsPresent)
+                {
+                    Write-Verbose -Message ($script:localizedData.Set_SqlDscRSServiceAccount_RestartingService -f $serviceName)
+
+                    Restart-SqlDscRSService -ServiceName $serviceName -Force
+                }
+            }
+            catch
+            {
+                $PSCmdlet.ThrowTerminatingError(
+                    [System.Management.Automation.ErrorRecord]::new(
+                        ($script:localizedData.Set_SqlDscRSServiceAccount_FailedToSet -f $instanceName, $_.Exception.Message),
+                        'SSRSSA0001',
+                        [System.Management.Automation.ErrorCategory]::InvalidOperation,
+                        $Configuration
+                    )
+                )
+            }
+        }
+
+        if ($PassThru.IsPresent)
+        {
+            return $Configuration
+        }
+    }
+}