Tests if permissions are set on a file, directory, registry key, or certificate's private key/key container.
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>]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.
| 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 |
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 |
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.
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.
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.
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.