Get-SqlDscServerPermission: Check for both login and role

CHANGELOG.md

@@ -36,18 +36,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Fixed environment variable persistence by using $GITHUB_ENV instead of
     job-level env declaration.
 - `Grant-SqlDscServerPermission`
-  - Added new public command to grant server permissions to a principal (Login or ServerRole) on a SQL Server Database Engine instance.
+  - Added new public command to grant server permissions to a principal
+    (Login or ServerRole) on a SQL Server Database Engine instance.
 - `Deny-SqlDscServerPermission`
-  - Added new public command to deny server permissions to a principal (Login or ServerRole).
+  - Added new public command to deny server permissions to a principal
+    (Login or ServerRole).
 - `Revoke-SqlDscServerPermission`
-  - Added new public command to revoke server permissions from a principal (Login or ServerRole).
+  - Added new public command to revoke server permissions from a principal
+    (Login or ServerRole).
 - `Test-SqlDscServerPermission`
-  - Added new public command with Grant/Deny parameter sets (and `-WithGrant`) to test server permissions for a principal.
+  - Added new public command with Grant/Deny parameter sets (and `-WithGrant`)
+    to test server permissions for a principal.
 - `Assert-SqlDscLogin`
   - Added new public command to validate that a specified SQL Server principal
     is a login.
 - `Enable-SqlDscLogin`
   - Added new public command to enable a SQL Server login.
+- `Get-SqlDscServerPermission`
+  - Enhanced command to support pipeline input for Login and ServerRole
+    objects while maintaining backward compatibility with the original
+    parameter set.
 - `Disable-SqlDscLogin`
   - Added new public command to disable a SQL Server login.
 - `Test-SqlDscIsLoginEnabled`
@@ -88,6 +96,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Added documentation for `SqlIntegrationTest` user and
     `IntegrationTestSqlLogin` login.
   - Added run order information for `New-SqlDscLogin` integration test.
+- `Get-SqlDscServerPermission`
+  - Enhanced the command to support server roles in addition to logins by
+    utilizing `Test-SqlDscIsRole` alongside the existing `Test-SqlDscIsLogin`
+    check.
+  - The command now accepts both login principals and server role principals
+    as the `Name` parameter (issue [#2063](https://github.com/dsccommunity/SqlServerDsc/issues/2063)).
 - `azure-pipelines.yml`
   - Remove `windows-2019` images fixes [#2106](https://github.com/dsccommunity/SqlServerDsc/issues/2106).
   - Move individual tasks to `windows-latest`.

RequiredModules.psd1

@@ -28,7 +28,7 @@
     Sampler                        = 'latest'
     'Sampler.GitHubTasks'          = 'latest'
     MarkdownLinkCheck              = 'latest'
-    'DscResource.Test'             = 'latest'
+    'DscResource.Test'             = '0.17.2'
     xDscResourceDesigner           = 'latest'
 
     # Build dependencies needed for using the module

azure-pipelines.yml

@@ -303,7 +303,6 @@ stages:
                   'tests/Integration/Commands/Get-SqlDscServerPermission.Integration.Tests.ps1'
                   'tests/Integration/Commands/Test-SqlDscServerPermission.Integration.Tests.ps1'
                   'tests/Integration/Commands/Deny-SqlDscServerPermission.Integration.Tests.ps1'
-                  'tests/Integration/Commands/Revoke-SqlDscServerPermission.Integration.Tests.ps1'
                   'tests/Integration/Commands/Get-SqlDscDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/New-SqlDscDatabase.Integration.Tests.ps1'
                   'tests/Integration/Commands/Set-SqlDscDatabase.Integration.Tests.ps1'
@@ -315,9 +314,9 @@ stages:
                   # Group 8
                   'tests/Integration/Commands/Remove-SqlDscAgentAlert.Integration.Tests.ps1'
                   'tests/Integration/Commands/Remove-SqlDscDatabase.Integration.Tests.ps1'
+                  'tests/Integration/Commands/Revoke-SqlDscServerPermission.Integration.Tests.ps1'
                   'tests/Integration/Commands/Remove-SqlDscRole.Integration.Tests.ps1'
                   'tests/Integration/Commands/Remove-SqlDscLogin.Integration.Tests.ps1'
-
                   # Group 9
                   'tests/Integration/Commands/Uninstall-SqlDscServer.Integration.Tests.ps1'
               )

source/Public/Deny-SqlDscServerPermission.ps1

@@ -104,25 +104,19 @@ function Deny-SqlDscServerPermission
                 $permissionSet.$permissionName = $true
             }
 
-            # Get the permissions names that are set to $true in the ServerPermissionSet.
-            $permissionName = $permissionSet |
-                Get-Member -MemberType 'Property' |
-                Select-Object -ExpandProperty 'Name' |
-                Where-Object -FilterScript {
-                    $permissionSet.$_
-                }
-
             try
             {
                 $serverObject.Deny($permissionSet, $principalName)
             }
             catch
             {
-                $errorMessage = $script:localizedData.ServerPermission_Deny_FailedToDenyPermission -f $principalName, $serverObject.InstanceName
+                $errorMessage = $script:localizedData.ServerPermission_Deny_FailedToDenyPermission -f $principalName, $serverObject.InstanceName, ($Permission -join ',')
+
+                $exception = [System.InvalidOperationException]::new($errorMessage, $_.Exception)
 
                 $PSCmdlet.ThrowTerminatingError(
                     [System.Management.Automation.ErrorRecord]::new(
-                        $errorMessage,
+                        $exception,
                         'DSDSP0001', # cSpell: disable-line
                         [System.Management.Automation.ErrorCategory]::InvalidOperation,
                         $principalName

source/Public/Get-SqlDscServerPermission.ps1

@@ -1,16 +1,38 @@
 <#
     .SYNOPSIS
-        Returns the current permissions for the principal.
+        Returns the current permissions for a SQL Server login or server role.
 
     .DESCRIPTION
-        Returns the current permissions for the principal.
+        Returns the current permissions for a SQL Server login or server role.
+        The command can retrieve permissions for both user-defined and built-in
+        server principals including SQL Server logins and server roles.
+
+        The command supports two modes of operation:
+        1. By name: Specify ServerObject, Name, and optionally PrincipalType
+        2. By object: Pass Login or ServerRole objects via pipeline
 
     .PARAMETER ServerObject
-        Specifies current server connection object.
+        Specifies current server connection object. This parameter is used in the
+        default parameter set for backward compatibility.
 
     .PARAMETER Name
-        Specifies the name of the principal for which the permissions are
-        returned.
+        Specifies the name of the SQL Server login or server role for which
+        the permissions are returned. This parameter is used in the default
+        parameter set for backward compatibility.
+
+    .PARAMETER PrincipalType
+        Specifies the type(s) of principal to check. Valid values are 'Login'
+        and 'Role'. If not specified, both login and role checks will be performed.
+        If specified, only the specified type(s) will be checked. This parameter
+        is used in the default parameter set for backward compatibility.
+
+    .PARAMETER Login
+        Specifies the Login object for which the permissions are returned.
+        This parameter accepts pipeline input.
+
+    .PARAMETER ServerRole
+        Specifies the ServerRole object for which the permissions are returned.
+        This parameter accepts pipeline input.
 
     .OUTPUTS
         [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo[]]
@@ -21,51 +43,157 @@
 
         Get the permissions for the principal 'MyPrincipal'.
 
+    .EXAMPLE
+        $serverInstance = Connect-SqlDscDatabaseEngine
+        Get-SqlDscServerPermission -ServerObject $serverInstance -Name 'sysadmin'
+
+        Get the permissions for the server role 'sysadmin'.
+
+    .EXAMPLE
+        $serverInstance = Connect-SqlDscDatabaseEngine
+        Get-SqlDscServerPermission -ServerObject $serverInstance -Name 'MyLogin' -PrincipalType 'Login'
+
+        Get the permissions for the login 'MyLogin', only checking if it exists as a login.
+
+    .EXAMPLE
+        $serverInstance = Connect-SqlDscDatabaseEngine
+        Get-SqlDscServerPermission -ServerObject $serverInstance -Name 'MyRole' -PrincipalType 'Role'
+
+        Get the permissions for the server role 'MyRole', only checking if it exists as a role.
+
+    .EXAMPLE
+        $serverInstance = Connect-SqlDscDatabaseEngine
+        $login = $serverInstance | Get-SqlDscLogin -Name 'MyLogin'
+
+        Get-SqlDscServerPermission -Login $login
+
+        Get the permissions for the login 'MyLogin' using a Login object.
+
+    .EXAMPLE
+        $serverInstance = Connect-SqlDscDatabaseEngine
+        $role = $serverInstance | Get-SqlDscRole -Name 'MyRole'
+
+        $role | Get-SqlDscServerPermission
+
+        Get the permissions for the server role 'MyRole' using a ServerRole object from the pipeline.
+
+    .EXAMPLE
+        $serverInstance = Connect-SqlDscDatabaseEngine
+
+        $serverInstance | Get-SqlDscLogin | Get-SqlDscServerPermission
+
+        Get the permissions for all logins from the pipeline.
+
     .NOTES
         If specifying `-ErrorAction 'SilentlyContinue'` then the command will silently
         ignore if the principal (parameter **Name**) is not present. In such case the
         command will return `$null`. If specifying `-ErrorAction 'Stop'` the command
         will throw an error if the principal is missing.
+
+        The Login or ServerRole object must come from the same SQL Server instance
+        where the permissions will be retrieved.
 #>
 function Get-SqlDscServerPermission
 {
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseOutputTypeCorrectly', '', Justification = 'Because the rule does not understands that the command returns [System.String[]] when using , (comma) in the return statement')]
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('UseSyntacticallyCorrectExamples', '', Justification = 'Because the rule does not yet support parsing the code when a parameter type is not available. The ScriptAnalyzer rule UseSyntacticallyCorrectExamples will always error in the editor due to https://github.com/indented-automation/Indented.ScriptAnalyzerRules/issues/8.')]
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('AvoidThrowOutsideOfTry', '', Justification = 'Because the code throws based on an prior expression')]
-    [CmdletBinding()]
+    [CmdletBinding(DefaultParameterSetName = 'ByName')]
     [OutputType([Microsoft.SqlServer.Management.Smo.ServerPermissionInfo[]])]
     param
     (
-        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'ByName')]
         [Microsoft.SqlServer.Management.Smo.Server]
         $ServerObject,
 
-        [Parameter(Mandatory = $true)]
+        [Parameter(Mandatory = $true, ParameterSetName = 'ByName')]
         [System.String]
-        $Name
+        $Name,
+
+        [Parameter(ParameterSetName = 'ByName')]
+        [ValidateSet('Login', 'Role')]
+        [System.String[]]
+        $PrincipalType,
+
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'Login')]
+        [Microsoft.SqlServer.Management.Smo.Login]
+        $Login,
+
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'ServerRole')]
+        [Microsoft.SqlServer.Management.Smo.ServerRole]
+        $ServerRole
     )
 
     # cSpell: ignore GSDSP
     process
     {
         $getSqlDscServerPermissionResult = $null
 
-        $testSqlDscIsLoginParameters = @{
-            ServerObject = $ServerObject
-            Name         = $Name
+        # Determine which parameter set we're using and set up variables accordingly
+        if ($PSCmdlet.ParameterSetName -eq 'Login')
+        {
+            $principalName = $Login.Name
+            $serverObject = $Login.Parent
+            $isLogin = $true
+            $isRole = $false
+        }
+        elseif ($PSCmdlet.ParameterSetName -eq 'ServerRole')
+        {
+            $principalName = $ServerRole.Name
+            $serverObject = $ServerRole.Parent
+            $isLogin = $false
+            $isRole = $true
         }
+        else
+        {
+            # ByName parameter set (default for backward compatibility)
+            $principalName = $Name
+            $serverObject = $ServerObject
 
-        $isLogin = Test-SqlDscIsLogin @testSqlDscIsLoginParameters
+            $testSqlDscIsPrincipalParameters = @{
+                ServerObject = $serverObject
+                Name         = $principalName
+            }
+
+            # Determine which checks to perform based on PrincipalType parameter
+            $checkLogin = $true
+            $checkRole = $true
+
+            if ($PSBoundParameters.ContainsKey('PrincipalType'))
+            {
+                $checkLogin = $PrincipalType -contains 'Login'
+                $checkRole = $PrincipalType -contains 'Role'
+            }
+
+            # Perform the appropriate checks
+            $isLogin = if ($checkLogin)
+            {
+                Test-SqlDscIsLogin @testSqlDscIsPrincipalParameters
+            }
+            else
+            {
+                $false
+            }
+
+            $isRole = if ($checkRole)
+            {
+                Test-SqlDscIsRole @testSqlDscIsPrincipalParameters
+            }
+            else
+            {
+                $false
+            }
+        }
 
-        if ($isLogin)
+        if ($isLogin -or $isRole)
         {
-            $getSqlDscServerPermissionResult = $ServerObject.EnumServerPermissions($Name)
+            $getSqlDscServerPermissionResult = $serverObject.EnumServerPermissions($principalName)
         }
         else
         {
-            $missingPrincipalMessage = $script:localizedData.ServerPermission_MissingPrincipal -f $Name, $ServerObject.InstanceName
+            $missingPrincipalMessage = $script:localizedData.ServerPermission_MissingPrincipal -f $principalName, $serverObject.InstanceName
 
-            Write-Error -Message $missingPrincipalMessage -Category 'InvalidOperation' -ErrorId 'GSDSP0001' -TargetObject $Name
+            Write-Error -Message $missingPrincipalMessage -Category 'InvalidOperation' -ErrorId 'GSDSP0001' -TargetObject $principalName
         }
 
         return , [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo[]] $getSqlDscServerPermissionResult

source/Public/Grant-SqlDscServerPermission.ps1

@@ -119,14 +119,6 @@ function Grant-SqlDscServerPermission
                 $permissionSet.$permissionName = $true
             }
 
-            # Get the permissions names that are set to $true in the ServerPermissionSet.
-            $permissionName = $permissionSet |
-                Get-Member -MemberType 'Property' |
-                Select-Object -ExpandProperty 'Name' |
-                Where-Object -FilterScript {
-                    $permissionSet.$_
-                }
-
             try
             {
                 if ($WithGrant.IsPresent)
@@ -140,11 +132,13 @@ function Grant-SqlDscServerPermission
             }
             catch
             {
-                $errorMessage = $script:localizedData.ServerPermission_Grant_FailedToGrantPermission -f $principalName, $serverObject.InstanceName
+                $errorMessage = $script:localizedData.ServerPermission_Grant_FailedToGrantPermission -f $principalName, $serverObject.InstanceName, ($Permission -join ', ')
+
+                $exception = [System.InvalidOperationException]::new($errorMessage, $_.Exception)
 
                 $PSCmdlet.ThrowTerminatingError(
                     [System.Management.Automation.ErrorRecord]::new(
-                        $errorMessage,
+                        $exception,
                         'GSDSP0001', # cSpell: disable-line
                         [System.Management.Automation.ErrorCategory]::InvalidOperation,
                         $principalName

source/Public/Revoke-SqlDscServerPermission.ps1

@@ -117,14 +117,6 @@ function Revoke-SqlDscServerPermission
                 $permissionSet.$permissionName = $true
             }
 
-            # Get the permissions names that are set to $true in the ServerPermissionSet.
-            $permissionName = $permissionSet |
-                Get-Member -MemberType 'Property' |
-                Select-Object -ExpandProperty 'Name' |
-                Where-Object -FilterScript {
-                    $permissionSet.$_
-                }
-
             try
             {
                 if ($WithGrant.IsPresent)
@@ -138,11 +130,13 @@ function Revoke-SqlDscServerPermission
             }
             catch
             {
-                $errorMessage = $script:localizedData.ServerPermission_Revoke_FailedToRevokePermission -f $principalName, $serverObject.InstanceName
+                $errorMessage = $script:localizedData.ServerPermission_Revoke_FailedToRevokePermission -f $principalName, $serverObject.InstanceName, ($Permission -join ',')
+
+                $exception = [System.InvalidOperationException]::new($errorMessage, $_.Exception)
 
                 $PSCmdlet.ThrowTerminatingError(
                     [System.Management.Automation.ErrorRecord]::new(
-                        $errorMessage,
+                        $exception,
                         'RSDSP0001', # cSpell: disable-line
                         [System.Management.Automation.ErrorCategory]::InvalidOperation,
                         $principalName