Test‑SqlDscServerPermission - dsccommunity/SqlServerDsc GitHub Wiki

Tests if server permissions for a principal are in the desired state.

Test-SqlDscServerPermission -Login <Login> [-Deny] -Permission <SqlServerPermission[]> [-WithGrant]
 [-ExactMatch] [<CommonParameters>]

Test-SqlDscServerPermission -Login <Login> [-Grant] -Permission <SqlServerPermission[]> [-WithGrant]
 [-ExactMatch] [<CommonParameters>]

Test-SqlDscServerPermission -ServerRole <ServerRole> [-Deny] -Permission <SqlServerPermission[]> [-WithGrant]
 [-ExactMatch] [<CommonParameters>]

Test-SqlDscServerPermission -ServerRole <ServerRole> [-Grant] -Permission <SqlServerPermission[]> [-WithGrant]
 [-ExactMatch] [<CommonParameters>]

This command tests if server permissions for an existing principal on a SQL Server Database Engine instance are in the desired state. The principal can be specified as either a Login object (from Get-SqlDscLogin) or a ServerRole object (from Get-SqlDscRole).

$serverInstance = Connect-SqlDscDatabaseEngine
$login = $serverInstance | Get-SqlDscLogin -Name 'MyLogin'

$isInDesiredState = Test-SqlDscServerPermission -Login $login -Grant -Permission ConnectSql, ViewServerState

Tests if the specified permissions are granted to the login 'MyLogin'.

$serverInstance = Connect-SqlDscDatabaseEngine
$role = $serverInstance | Get-SqlDscRole -Name 'MyRole'

$isInDesiredState = $role | Test-SqlDscServerPermission -Grant -Permission AlterAnyDatabase -WithGrant

Tests if the specified permissions are granted with grant option to the role 'MyRole'.

$serverInstance = Connect-SqlDscDatabaseEngine
$login = $serverInstance | Get-SqlDscLogin -Name 'MyLogin'

$isInDesiredState = Test-SqlDscServerPermission -Login $login -Grant -Permission @()

Tests if the login 'MyLogin' has no permissions granted (empty permission set).

Specifies that the test should verify if the permissions are denied to the principal.

Type: SwitchParameter
Parameter Sets: LoginDeny, ServerRoleDeny
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

Specifies that the test should verify that only the specified permissions are present and no additional permissions exist in the specified state. When this parameter is not used, the test will return true if the specified permissions are present, regardless of any additional permissions.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

Specifies that the test should verify if the permissions are granted to the principal.

Type: SwitchParameter
Parameter Sets: LoginGrant, ServerRoleGrant
Aliases:

Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

Specifies the Login object for which the permissions are tested. This parameter accepts pipeline input.

Type: Login
Parameter Sets: LoginDeny, LoginGrant
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

Specifies the desired permissions. Specify multiple permissions by providing an array of SqlServerPermission enum values that should be present in the specified state. An empty collection can be specified to test that no permissions are set for the principal.

Type: SqlServerPermission[]
Parameter Sets: (All)
Aliases:
Accepted values: AdministerBulkOperations, AlterAnyAvailabilityGroup, AlterAnyConnection, AlterAnyCredential, AlterAnyDatabase, AlterAnyEndpoint, AlterAnyEventNotification, AlterAnyEventSession, AlterAnyEventSessionAddEvent, AlterAnyEventSessionAddTarget, AlterAnyEventSessionDisable, AlterAnyEventSessionDropEvent, AlterAnyEventSessionDropTarget, AlterAnyEventSessionEnable, AlterAnyEventSessionOption, AlterAnyLinkedServer, AlterAnyLogin, AlterAnyServerAudit, AlterAnyServerRole, AlterResources, AlterServerState, AlterSettings, AlterTrace, AuthenticateServer, ConnectAnyDatabase, ConnectSql, ControlServer, CreateAnyDatabase, CreateAnyEventSession, CreateAvailabilityGroup, CreateDdlEventNotification, CreateEndpoint, CreateLogin, CreateServerRole, CreateTraceEventNotification, DropAnyEventSession, ExternalAccessAssembly, ImpersonateAnyLogin, SelectAllUserSecurables, Shutdown, UnsafeAssembly, ViewAnyCryptographicallySecuredDefinition, ViewAnyDatabase, ViewAnyDefinition, ViewAnyErrorLog, ViewAnyPerformanceDefinition, ViewAnySecurityDefinition, ViewServerPerformanceState, ViewServerSecurityAudit, ViewServerSecurityState, ViewServerState

Required: True
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

Specifies the ServerRole object for which the permissions are tested. This parameter accepts pipeline input.

Type: ServerRole
Parameter Sets: ServerRoleDeny, ServerRoleGrant
Aliases:

Required: True
Position: Named
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

Specifies that the principal should have the right to grant other principals the same permission. This parameter is only valid when parameter Grant is used. When this parameter is used, the effective state tested will be 'GrantWithGrant'.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

The Login or ServerRole object must come from the same SQL Server instance where the permissions will be tested. If specifying -ErrorAction 'SilentlyContinue' then the command will silently continue if any errors occur. If specifying -ErrorAction 'Stop' the command will throw an error on any failure.