Test-Permission

Tests if permissions are set on a file, directory, registry key, or certificate's private key/key container.

Syntax

Test-Permission [-Path] <String> [-Identity] <String> [-Permission] <String[]> [[-ApplyTo] {Container | SubContainers | ContainerAndSubContainers | Leaves | ContainerAndLeaves | SubContainersAndLeaves | ContainerAndSubContainersAndLeaves | ChildContainers | ContainerAndChildContainers | ChildLeaves | ContainerAndChildLeaves | ChildContainersAndChildLeaves | ContainerAndChildContainersAndChildLeaves}] [-Inherited] [-Exact] [<CommonParameters>]

Description

Sometimes, you don't want to use Grant-Permission on a big tree. In these situations, use Test-Permission to see if permissions are set on a given path.

This function supports file system, registry, and certificate private key/key container permissions. You can also test the inheritance and propogation flags on containers, in addition to the permissions, with the ApplyTo parameter. See Grant-Permission documentation for an explanation of the ApplyTo parameter.

Inherited permissions on not checked by default. To check inherited permission, use the -Inherited switch.

By default, the permission check is not exact, i.e. the user may have additional permissions to what you're checking. If you want to make sure the user has exactly the permission you want, use the -Exact switch. Please note that by default, NTFS will automatically add/grant Synchronize permission on an item, which is handled by this function.

When checking for permissions on certificate private keys/key containers, if a certificate doesn't have a private key, $true is returned.

Related Commands

Parameters

Name Type Description Required? Pipeline Input Default Value
Path String

The path on which the permissions should be checked. Can be a file system or registry path.

true false
Identity String

The user or group whose permissions to check.

true false
Permission String[]

The permission to test for: e.g. FullControl, Read, etc. For file system items, use values from System.Security.AccessControl.FileSystemRights. For registry items, use values from System.Security.AccessControl.RegistryRights.

true false
ApplyTo ContainerInheritanceFlags

The container and inheritance flags to check. Ignored if Path is a file. These are ignored if not supplied. See Grant-Permission for detailed explanation of this parameter. This controls the inheritance and propagation flags. Default is full inheritance, e.g. ContainersAndSubContainersAndLeaves. This parameter is ignored if Path is to a leaf item.

false false
Inherited SwitchParameter

Include inherited permissions in the check.

false false False
Exact SwitchParameter

Check for the exact permissions, inheritance flags, and propagation flags, i.e. make sure the identity has only the permissions you specify.

false false False

Return Values

System.Boolean.

EXAMPLE 1

Test-Permission -Identity 'STARFLEET\JLPicard' -Permission 'FullControl' -Path 'C:\Enterprise\Bridge'

Demonstrates how to check that Jean-Luc Picard has FullControl permission on the C:\Enterprise\Bridge.

EXAMPLE 2

Test-Permission -Identity 'STARFLEET\GLaForge' -Permission 'WriteKey' -Path 'HKLM:\Software\Enterprise\Engineering'

Demonstrates how to check that Geordi LaForge can write registry keys at HKLM:\Software\Enterprise\Engineering.

EXAMPLE 3

Test-Permission -Identity 'STARFLEET\Worf' -Permission 'Write' -ApplyTo 'Container' -Path 'C:\Enterprise\Brig'

Demonstrates how to test for inheritance/propogation flags, in addition to permissions.

EXAMPLE 4

Test-Permission -Identity 'STARFLEET\Data' -Permission 'GenericWrite' -Path 'cert:\LocalMachine\My\1234567890ABCDEF1234567890ABCDEF12345678'

Demonstrates how to test for permissions on a certificate's private key/key container. If the certificate doesn't have a private key, returns $true.