Get-SqlDscServerPermission: Check for both login and role

CHANGELOG.md

@@ -88,6 +88,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,23 @@
 <#
     .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.
 
     .PARAMETER ServerObject
         Specifies current server connection object.
 
     .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.
+
+    .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.
 
     .OUTPUTS
         [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo[]]
@@ -21,6 +28,24 @@
 
         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.
+
     .NOTES
         If specifying `-ErrorAction 'SilentlyContinue'` then the command will silently
         ignore if the principal (parameter **Name**) is not present. In such case the
@@ -42,22 +67,54 @@ function Get-SqlDscServerPermission
 
         [Parameter(Mandatory = $true)]
         [System.String]
-        $Name
+        $Name,
+
+        [Parameter()]
+        [ValidateSet('Login', 'Role')]
+        [System.String[]]
+        $PrincipalType
     )
 
     # cSpell: ignore GSDSP
     process
     {
         $getSqlDscServerPermissionResult = $null
 
-        $testSqlDscIsLoginParameters = @{
+        $testSqlDscIsPrincipalParameters = @{
             ServerObject = $ServerObject
             Name         = $Name
         }
 
-        $isLogin = Test-SqlDscIsLogin @testSqlDscIsLoginParameters
+        # 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)
         }

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

tests/Integration/Commands/Get-SqlDscServerPermission.Integration.Tests.ps1

@@ -0,0 +1,216 @@
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '', Justification = 'Suppressing this rule because Script Analyzer does not understand Pester syntax.')]
+param ()
+
+BeforeDiscovery {
+    try
+    {
+        if (-not (Get-Module -Name 'DscResource.Test'))
+        {
+            # Assumes dependencies has been resolved, so if this module is not available, run 'noop' task.
+            if (-not (Get-Module -Name 'DscResource.Test' -ListAvailable))
+            {
+                # Redirect all streams to $null, except the error stream (stream 2)
+                & "$PSScriptRoot/../../../build.ps1" -Tasks 'noop' 3>&1 4>&1 5>&1 6>&1 > $null
+            }
+
+            # If the dependencies has not been resolved, this will throw an error.
+            Import-Module -Name 'DscResource.Test' -Force -ErrorAction 'Stop'
+        }
+    }
+    catch [System.IO.FileNotFoundException]
+    {
+        throw 'DscResource.Test module dependency not found. Please run ".\build.ps1 -ResolveDependency -Tasks build" first.'
+    }
+}
+
+BeforeAll {
+    $script:dscModuleName = 'SqlServerDsc'
+
+    Import-Module -Name $script:dscModuleName
+}
+
+Describe 'Get-SqlDscServerPermission' -Tag @('Integration_SQL2016', 'Integration_SQL2017', 'Integration_SQL2019', 'Integration_SQL2022') {
+    BeforeAll {
+        # Starting the named instance SQL Server service prior to running tests.
+        Start-Service -Name 'MSSQL$DSCSQLTEST' -Verbose -ErrorAction 'Stop'
+
+        $script:instanceName = 'DSCSQLTEST'
+        $script:computerName = Get-ComputerName
+    }
+
+    AfterAll {
+        # Stop the named instance SQL Server service to save memory on the build worker.
+        Stop-Service -Name 'MSSQL$DSCSQLTEST' -Verbose -ErrorAction 'Stop'
+    }
+
+    Context 'When connecting to SQL Server instance' {
+        BeforeAll {
+            $sqlAdministratorUserName = 'SqlAdmin' # Using computer name as NetBIOS name throw exception.
+            $sqlAdministratorPassword = ConvertTo-SecureString -String 'P@ssw0rd1' -AsPlainText -Force
+
+            $script:sqlAdminCredential = [System.Management.Automation.PSCredential]::new($sqlAdministratorUserName, $sqlAdministratorPassword)
+
+            $script:serverObject = Connect-SqlDscDatabaseEngine -InstanceName $script:instanceName -Credential $script:sqlAdminCredential
+        }
+
+        AfterAll {
+            Disconnect-SqlDscDatabaseEngine -ServerObject $script:serverObject
+        }
+
+        Context 'When getting permissions for valid SQL logins' {
+            It 'Should return permissions for sa login' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'sa'
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+
+            It 'Should return permissions for sa login using pipeline' {
+                $result = $script:serverObject | Get-SqlDscServerPermission -Name 'sa'
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+        }
+
+        Context 'When getting permissions for valid Windows logins' {
+            It 'Should return permissions for SqlAdmin Windows login' {
+                $windowsLogin = '{0}\SqlAdmin' -f $script:computerName
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name $windowsLogin
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+
+            It 'Should return permissions for NT AUTHORITY\SYSTEM login' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'NT AUTHORITY\SYSTEM'
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+        }
+
+        Context 'When getting permissions for valid server roles' {
+            It 'Should return permissions for sysadmin server role' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'sysadmin'
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+
+            It 'Should return permissions for public server role' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'public'
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+
+            It 'Should return permissions for serveradmin server role' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'serveradmin'
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+
+            It 'Should return permissions for securityadmin server role' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'securityadmin'
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+        }
+
+        Context 'When getting permissions for invalid principals' {
+            It 'Should throw error for non-existent login with ErrorAction Stop' {
+                { Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'NonExistentLogin123' -ErrorAction 'Stop' } |
+                    Should -Throw -ExpectedMessage "*is not a login nor role*"
+            }
+
+            It 'Should return null for non-existent login with ErrorAction SilentlyContinue' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'NonExistentLogin123' -ErrorAction 'SilentlyContinue'
+
+                $result | Should -BeNullOrEmpty
+            }
+
+            It 'Should throw error for non-existent server role with ErrorAction Stop' {
+                { Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'NonExistentRole123' -ErrorAction 'Stop' } |
+                    Should -Throw -ExpectedMessage "*is not a login nor role*"
+            }
+
+            It 'Should return null for non-existent server role with ErrorAction SilentlyContinue' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'NonExistentRole123' -ErrorAction 'SilentlyContinue'
+
+                $result | Should -BeNullOrEmpty
+            }
+        }
+
+        Context 'When verifying permission properties' {
+            BeforeAll {
+                # Get permissions for a known principal that should have permissions
+                $script:testPermissions = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'sysadmin'
+            }
+
+            It 'Should return ServerPermissionInfo objects with PermissionState property' {
+                $script:testPermissions | Should -Not -BeNullOrEmpty
+
+                foreach ($permission in $script:testPermissions) {
+                    $permission.PermissionState | Should -BeIn @('Grant', 'Deny', 'GrantWithGrant')
+                }
+            }
+
+            It 'Should return ServerPermissionInfo objects with PermissionType property' {
+                $script:testPermissions | Should -Not -BeNullOrEmpty
+
+                foreach ($permission in $script:testPermissions) {
+                    $permission.PermissionType | Should -Not -BeNullOrEmpty
+                    $permission.PermissionType | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionSet]
+                }
+            }
+        }
+
+        Context 'When using PrincipalType parameter' {
+            It 'Should return permissions for sa login when PrincipalType is Login' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'sa' -PrincipalType 'Login'
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+
+            It 'Should return permissions for sysadmin role when PrincipalType is Role' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'sysadmin' -PrincipalType 'Role'
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+
+            It 'Should return permissions for sa login when PrincipalType is both Login and Role' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'sa' -PrincipalType 'Login', 'Role'
+
+                $result | Should -Not -BeNullOrEmpty
+                $result | Should -BeOfType [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo]
+            }
+
+            It 'Should throw error when looking for login as role' {
+                { Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'sa' -PrincipalType 'Role' -ErrorAction 'Stop' } |
+                    Should -Throw -ExpectedMessage "*is not a login nor role*"
+            }
+
+            It 'Should throw error when looking for role as login' {
+                { Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'sysadmin' -PrincipalType 'Login' -ErrorAction 'Stop' } |
+                    Should -Throw -ExpectedMessage "*is not a login nor role*"
+            }
+
+            It 'Should return null when looking for login as role with SilentlyContinue' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'sa' -PrincipalType 'Role' -ErrorAction 'SilentlyContinue'
+
+                $result | Should -BeNullOrEmpty
+            }
+
+            It 'Should return null when looking for role as login with SilentlyContinue' {
+                $result = Get-SqlDscServerPermission -ServerObject $script:serverObject -Name 'sysadmin' -PrincipalType 'Login' -ErrorAction 'SilentlyContinue'
+
+                $result | Should -BeNullOrEmpty
+            }
+        }
+    }
+}