Grants permission on a file, directory or registry key.
Grant-Permission [-Path] <String> [-Identity] <String> [-Permission] <String[]> [[-ApplyTo] {Container | SubContainers | ContainerAndSubContainers | Leaves | ContainerAndLeaves | SubContainersAndLeaves | ContainerAndSubContainersAndLeaves | ChildContainers | ContainerAndChildContainers | ChildLeaves | ContainerAndChildLeaves | ChildContainersAndChildLeaves | ContainerAndChildContainersAndChildLeaves}] [-Clear] [-WhatIf] [-Confirm] [<CommonParameters>]
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.
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 | |
Permission | 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 | ContainerAndSubContainersAndLeaves |
Clear | SwitchParameter | Removes all non-inherited permissions on the item. | false | false | False |
WhatIf | SwitchParameter | false | false | ||
Confirm | SwitchParameter | false | false | ||
CommonParameters | This cmdlet supports common parameters. For more information type Get-Help about_CommonParameters . |
Grant-Permission -Identity ENTERPRISE\Engineers -Permission FullControl -Path C:\EngineRoom
Grants the Enterprise's engineering group full control on the engine room. Very important if you want to get anywhere.
Grant-Permission -Identity ENTERPRISE\Interns -Permission 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.
Grant-Permission -Identity ENTERPRISE\Engineers -Permission 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
.