|
1 | 1 | <# |
2 | 2 | .SYNOPSIS |
3 | | - Returns the current permissions for the principal. |
| 3 | + Returns the current permissions for a SQL Server login or server role. |
4 | 4 |
|
5 | 5 | .DESCRIPTION |
6 | | - Returns the current permissions for the principal. |
| 6 | + Returns the current permissions for a SQL Server login or server role. |
| 7 | + The command can retrieve permissions for both user-defined and built-in |
| 8 | + server principals including SQL Server logins and server roles. |
| 9 | +
|
| 10 | + The command supports two modes of operation: |
| 11 | + 1. By name: Specify ServerObject, Name, and optionally PrincipalType |
| 12 | + 2. By object: Pass Login or ServerRole objects via pipeline |
7 | 13 |
|
8 | 14 | .PARAMETER ServerObject |
9 | | - Specifies current server connection object. |
| 15 | + Specifies current server connection object. This parameter is used in the |
| 16 | + default parameter set for backward compatibility. |
10 | 17 |
|
11 | 18 | .PARAMETER Name |
12 | | - Specifies the name of the principal for which the permissions are |
13 | | - returned. |
| 19 | + Specifies the name of the SQL Server login or server role for which |
| 20 | + the permissions are returned. This parameter is used in the default |
| 21 | + parameter set for backward compatibility. |
| 22 | +
|
| 23 | + .PARAMETER PrincipalType |
| 24 | + Specifies the type(s) of principal to check. Valid values are 'Login' |
| 25 | + and 'Role'. If not specified, both login and role checks will be performed. |
| 26 | + If specified, only the specified type(s) will be checked. This parameter |
| 27 | + is used in the default parameter set for backward compatibility. |
| 28 | +
|
| 29 | + .PARAMETER Login |
| 30 | + Specifies the Login object for which the permissions are returned. |
| 31 | + This parameter accepts pipeline input. |
| 32 | +
|
| 33 | + .PARAMETER ServerRole |
| 34 | + Specifies the ServerRole object for which the permissions are returned. |
| 35 | + This parameter accepts pipeline input. |
14 | 36 |
|
15 | 37 | .OUTPUTS |
16 | 38 | [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo[]] |
|
21 | 43 |
|
22 | 44 | Get the permissions for the principal 'MyPrincipal'. |
23 | 45 |
|
| 46 | + .EXAMPLE |
| 47 | + $serverInstance = Connect-SqlDscDatabaseEngine |
| 48 | + Get-SqlDscServerPermission -ServerObject $serverInstance -Name 'sysadmin' |
| 49 | +
|
| 50 | + Get the permissions for the server role 'sysadmin'. |
| 51 | +
|
| 52 | + .EXAMPLE |
| 53 | + $serverInstance = Connect-SqlDscDatabaseEngine |
| 54 | + Get-SqlDscServerPermission -ServerObject $serverInstance -Name 'MyLogin' -PrincipalType 'Login' |
| 55 | +
|
| 56 | + Get the permissions for the login 'MyLogin', only checking if it exists as a login. |
| 57 | +
|
| 58 | + .EXAMPLE |
| 59 | + $serverInstance = Connect-SqlDscDatabaseEngine |
| 60 | + Get-SqlDscServerPermission -ServerObject $serverInstance -Name 'MyRole' -PrincipalType 'Role' |
| 61 | +
|
| 62 | + Get the permissions for the server role 'MyRole', only checking if it exists as a role. |
| 63 | +
|
| 64 | + .EXAMPLE |
| 65 | + $serverInstance = Connect-SqlDscDatabaseEngine |
| 66 | + $login = $serverInstance | Get-SqlDscLogin -Name 'MyLogin' |
| 67 | +
|
| 68 | + Get-SqlDscServerPermission -Login $login |
| 69 | +
|
| 70 | + Get the permissions for the login 'MyLogin' using a Login object. |
| 71 | +
|
| 72 | + .EXAMPLE |
| 73 | + $serverInstance = Connect-SqlDscDatabaseEngine |
| 74 | + $role = $serverInstance | Get-SqlDscRole -Name 'MyRole' |
| 75 | +
|
| 76 | + $role | Get-SqlDscServerPermission |
| 77 | +
|
| 78 | + Get the permissions for the server role 'MyRole' using a ServerRole object from the pipeline. |
| 79 | +
|
| 80 | + .EXAMPLE |
| 81 | + $serverInstance = Connect-SqlDscDatabaseEngine |
| 82 | +
|
| 83 | + $serverInstance | Get-SqlDscLogin | Get-SqlDscServerPermission |
| 84 | +
|
| 85 | + Get the permissions for all logins from the pipeline. |
| 86 | +
|
24 | 87 | .NOTES |
25 | 88 | If specifying `-ErrorAction 'SilentlyContinue'` then the command will silently |
26 | 89 | ignore if the principal (parameter **Name**) is not present. In such case the |
27 | 90 | command will return `$null`. If specifying `-ErrorAction 'Stop'` the command |
28 | 91 | will throw an error if the principal is missing. |
| 92 | +
|
| 93 | + The Login or ServerRole object must come from the same SQL Server instance |
| 94 | + where the permissions will be retrieved. |
29 | 95 | #> |
30 | 96 | function Get-SqlDscServerPermission |
31 | 97 | { |
32 | 98 | [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')] |
33 | 99 | [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.')] |
34 | 100 | [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('AvoidThrowOutsideOfTry', '', Justification = 'Because the code throws based on an prior expression')] |
35 | | - [CmdletBinding()] |
| 101 | + [CmdletBinding(DefaultParameterSetName = 'ByName')] |
36 | 102 | [OutputType([Microsoft.SqlServer.Management.Smo.ServerPermissionInfo[]])] |
37 | 103 | param |
38 | 104 | ( |
39 | | - [Parameter(Mandatory = $true, ValueFromPipeline = $true)] |
| 105 | + [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'ByName')] |
40 | 106 | [Microsoft.SqlServer.Management.Smo.Server] |
41 | 107 | $ServerObject, |
42 | 108 |
|
43 | | - [Parameter(Mandatory = $true)] |
| 109 | + [Parameter(Mandatory = $true, ParameterSetName = 'ByName')] |
44 | 110 | [System.String] |
45 | | - $Name |
| 111 | + $Name, |
| 112 | + |
| 113 | + [Parameter(ParameterSetName = 'ByName')] |
| 114 | + [ValidateSet('Login', 'Role')] |
| 115 | + [System.String[]] |
| 116 | + $PrincipalType, |
| 117 | + |
| 118 | + [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'Login')] |
| 119 | + [Microsoft.SqlServer.Management.Smo.Login] |
| 120 | + $Login, |
| 121 | + |
| 122 | + [Parameter(Mandatory = $true, ValueFromPipeline = $true, ParameterSetName = 'ServerRole')] |
| 123 | + [Microsoft.SqlServer.Management.Smo.ServerRole] |
| 124 | + $ServerRole |
46 | 125 | ) |
47 | 126 |
|
48 | 127 | # cSpell: ignore GSDSP |
49 | 128 | process |
50 | 129 | { |
51 | 130 | $getSqlDscServerPermissionResult = $null |
52 | 131 |
|
53 | | - $testSqlDscIsLoginParameters = @{ |
54 | | - ServerObject = $ServerObject |
55 | | - Name = $Name |
| 132 | + # Determine which parameter set we're using and set up variables accordingly |
| 133 | + if ($PSCmdlet.ParameterSetName -eq 'Login') |
| 134 | + { |
| 135 | + $principalName = $Login.Name |
| 136 | + $serverObject = $Login.Parent |
| 137 | + $isLogin = $true |
| 138 | + $isRole = $false |
| 139 | + } |
| 140 | + elseif ($PSCmdlet.ParameterSetName -eq 'ServerRole') |
| 141 | + { |
| 142 | + $principalName = $ServerRole.Name |
| 143 | + $serverObject = $ServerRole.Parent |
| 144 | + $isLogin = $false |
| 145 | + $isRole = $true |
56 | 146 | } |
| 147 | + else |
| 148 | + { |
| 149 | + # ByName parameter set (default for backward compatibility) |
| 150 | + $principalName = $Name |
| 151 | + $serverObject = $ServerObject |
57 | 152 |
|
58 | | - $isLogin = Test-SqlDscIsLogin @testSqlDscIsLoginParameters |
| 153 | + $testSqlDscIsPrincipalParameters = @{ |
| 154 | + ServerObject = $serverObject |
| 155 | + Name = $principalName |
| 156 | + } |
| 157 | + |
| 158 | + # Determine which checks to perform based on PrincipalType parameter |
| 159 | + $checkLogin = $true |
| 160 | + $checkRole = $true |
| 161 | + |
| 162 | + if ($PSBoundParameters.ContainsKey('PrincipalType')) |
| 163 | + { |
| 164 | + $checkLogin = $PrincipalType -contains 'Login' |
| 165 | + $checkRole = $PrincipalType -contains 'Role' |
| 166 | + } |
| 167 | + |
| 168 | + # Perform the appropriate checks |
| 169 | + $isLogin = if ($checkLogin) |
| 170 | + { |
| 171 | + Test-SqlDscIsLogin @testSqlDscIsPrincipalParameters |
| 172 | + } |
| 173 | + else |
| 174 | + { |
| 175 | + $false |
| 176 | + } |
| 177 | + |
| 178 | + $isRole = if ($checkRole) |
| 179 | + { |
| 180 | + Test-SqlDscIsRole @testSqlDscIsPrincipalParameters |
| 181 | + } |
| 182 | + else |
| 183 | + { |
| 184 | + $false |
| 185 | + } |
| 186 | + } |
59 | 187 |
|
60 | | - if ($isLogin) |
| 188 | + if ($isLogin -or $isRole) |
61 | 189 | { |
62 | | - $getSqlDscServerPermissionResult = $ServerObject.EnumServerPermissions($Name) |
| 190 | + $getSqlDscServerPermissionResult = $serverObject.EnumServerPermissions($principalName) |
63 | 191 | } |
64 | 192 | else |
65 | 193 | { |
66 | | - $missingPrincipalMessage = $script:localizedData.ServerPermission_MissingPrincipal -f $Name, $ServerObject.InstanceName |
| 194 | + $missingPrincipalMessage = $script:localizedData.ServerPermission_MissingPrincipal -f $principalName, $serverObject.InstanceName |
67 | 195 |
|
68 | | - Write-Error -Message $missingPrincipalMessage -Category 'InvalidOperation' -ErrorId 'GSDSP0001' -TargetObject $Name |
| 196 | + Write-Error -Message $missingPrincipalMessage -Category 'InvalidOperation' -ErrorId 'GSDSP0001' -TargetObject $principalName |
69 | 197 | } |
70 | 198 |
|
71 | 199 | return , [Microsoft.SqlServer.Management.Smo.ServerPermissionInfo[]] $getSqlDscServerPermissionResult |
|
0 commit comments