Grant-Permissions

Grants permission on a file, directory or registry key.

Syntax

Grant-Permissions [-Path] <String> [-Identity] <String> [-Permissions] <String[]> [[-ApplyTo] {Container | SubContainers | ContainerAndSubContainers | Leaves | ContainerAndLeaves | SubContainersAndLeaves | ContainerAndSubContainersAndLeaves | ChildContainers | ContainerAndChildContainers | ChildLeaves | ContainerAndChildLeaves | ChildContainersAndChildLeaves | ContainerAndChildContainersAndChildLeaves}] [-Clear] [-WhatIf] [-Confirm] [<CommonParameters>]

Description

Granting access to a file system entry or registry key requires a lot of steps. This method reduces it to one call. Very helpful.

It has the advantage that it will set permissions on a file system object or a registry. If Path is absolute, the correct provider (file system or registry) is used. If Path is relative, the provider of the current location will be used.

The Permissions attribute can be a list of FileSystemRights or RegistryRights.

This command will show you the values for the FileSystemRights:

[Enum]::GetValues([Security.AccessControl.FileSystemRights])

This command will show you the values for the RegistryRights:

[Enum]::GetValues([Security.AccessControl.RegistryRights])

When setting permissions on a container (directory/registry key) You can control inheritance and propagation flags using the ApplyTo parameter. There are 13 possible combinations. Examples work best. Here is a simple hierarchy:

    C
   / \
  CC CL
 /  \
GC  GL

C is the Container permissions are getting set on CC is a Child Container. CL is a Child ** Leaf GC is a Grandchild Container and includes all sub-containers below it. GL is a Grandchild Leaf.

The ApplyTo parameter takes one of the following 13 values and applies permissions to:

The following table maps ContainerInheritanceFlags values to the actual InheritanceFlags and PropagationFlags values used:

ContainerInheritanceFlags                   InheritanceFlags                 PropagationFlags
-------------------------                   ----------------                 ----------------
Container                                   None                             None
SubContainers                               ContainerInherit                 InheritOnly
Leaves                                      ObjectInherit                    InheritOnly
ChildContainers                             ContainerInherit                 InheritOnly,
                                                                             NoPropagateInherit
ChildLeaves                                 ObjectInherit                    InheritOnly
ContainerAndSubContainers                   ContainerInherit                 None
ContainerAndLeaves                          ObjectInherit                    None
SubContainerAndLeaves                       ContainerInherit,ObjectInherit   InheritOnly
ContainerAndChildContainers                 ContainerInherit                 None
ContainerAndChildLeaves                     ObjectInherit                    None
ContainerAndChildContainersAndChildLeaves   ContainerInherit,ObjectInherit   NoPropagateInherit
ContainerAndSubContainersAndLeaves          ContainerInherit,ObjectInherit   None
ChildContainersAndChildLeaves               ContainerInherit,ObjectInherit   InheritOnly

The above information adpated from Manage Access to Windows Objects with ACLs and the .NET Framework, published in the November 2004 copy of MSDN Magazine.

Related Commands

Parameters

Name Type Description Required? Pipeline Input Default Value
Path String The path on which the permissions should be granted. Can be a file system or registry path. true false
Identity String The user or group getting the permissions true false
Permissions String[] The permission: 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 How to apply container permissions. 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
Clear SwitchParameter Removes all non-inherited permissions on the item. false false
WhatIf SwitchParameter false false
Confirm SwitchParameter false false
CommonParameters This cmdlet supports common parameters. For more information type
Get-Help about_CommonParameters.

EXAMPLE 1

Grant-Permissions -Identity ENTERPRISE\Engineers -Permissions FullControl -Path C:\EngineRoom

Grants the Enterprise's engineering group full control on the engine room. Very important if you want to get anywhere.

EXAMPLE 2

Grant-Permissions -Identity ENTERPRISE\Interns -Permissions ReadKey,QueryValues,EnumerateSubKeys -Path rklm:\system\WarpDrive

Grants the Enterprise's interns access to read about the warp drive. They need to learn someday, but at least they can't change anything.

EXAMPLE 3

Grant-Permissions -Identity ENTERPRISE\Engineers -Permissions FullControl -Path C:\EngineRoom -Clear

Grants the Enterprise's engineering group full control on the engine room. Any non-inherited, existing access rules are removed from C:\EngineRoom.