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`.

azure-pipelines.yml

@@ -317,7 +317,6 @@ stages:
                   'tests/Integration/Commands/Remove-SqlDscDatabase.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/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/Test-SqlDscIsRole.ps1

@@ -1,15 +1,15 @@
 <#
     .SYNOPSIS
-        Returns whether the database principal exists and is a database role.
+        Returns whether the server principal exists and is a server role.
 
     .DESCRIPTION
-        Returns whether the database principal exist and is a database role.
+        Returns whether the server principal exist and is a server role.
 
     .PARAMETER ServerObject
         Specifies current server connection object.
 
     .PARAMETER Name
-        Specifies the name of the database principal.
+        Specifies the name of the server principal.
 
     .OUTPUTS
         [System.Boolean]
@@ -18,7 +18,7 @@
         $serverInstance = Connect-SqlDscDatabaseEngine
         Test-SqlDscIsRole -ServerObject $serverInstance -Name 'MyPrincipal'
 
-        Returns $true if the principal exist as role, if not $false is returned.
+        Returns $true if the principal exist as a server role, if not $false is returned.
 #>
 function Test-SqlDscIsRole
 {

tests/Integration/Commands/Assert-SqlDscLogin.Integration.Tests.ps1

@@ -53,6 +53,10 @@ Describe 'Assert-SqlDscLogin' -Tag @('Integration_SQL2016', 'Integration_SQL2017
             $script:serverObject = Connect-SqlDscDatabaseEngine -InstanceName $script:instanceName -Credential $script:sqlAdminCredential
         }
 
+        AfterAll {
+            Disconnect-SqlDscDatabaseEngine -ServerObject $script:serverObject
+        }
+
         Context 'When a login exists' {
             It 'Should not throw an error for sa login' {
                 { Assert-SqlDscLogin -ServerObject $script:serverObject -Name 'sa' } | Should -Not -Throw