Grant-Permission

Grants permission on a file, directory, registry key, or certificate's private key/key container.

Syntax

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

Description

Granting access to a file system entry, registry key, or certificate's private key/key container requires a lot of steps. This method reduces it to one call. Very helpful.

Beginning with Carbon 2.0, permissions are only granted if they don't exist on an item, which saves a lot of time when granting permissions on large directory trees. If you always want to grant permissions, use the Force switch.

Beginning with Carbon 2.0, this function returns any new/updated access rules set on Path.

It has the advantage that it will set permissions on a file system object, a registry key, or a certificate's private key/key container. 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, RegistryRights, or CryptoKeyRights.

These commands will show you the values for the appropriate permissions for your object:

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

Directories and Registry Keys

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.

If you prefer to speak in InheritanceFlags or PropagationFlags, you can use the ConvertTo-ContainerInheritaceFlags function to convert your flags into Carbon's flags.

Certificate Private Keys/Key Containers

When setting permissions on a certificate's private key/key container, if a certificate doesn't have a private key, it is ignored and no permissions are set. Since certificate's are always leaves, the ApplyTo parameter is ignored.

When using the -Clear switch, note that the local Administrators account will always remain. In testing on Windows 2012 R2, we noticed that when Administrators access was removed, you couldn't read the key anymore.

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, registry, or certificate 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
PassThru SwitchParameter

Returns an object representing the permission created or set on the Path. The returned object will have a Path propery added to it so it can be piped to any cmdlet that uses a path.

The PassThru switch is new in Carbon 2.0.

false false False
Force SwitchParameter

Grants permissions, even if they are already present.

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.

Return Values

System.Security.AccessControl.AccessRule. When setting permissions on a file or directory, a System.Security.AccessControl.FileSystemAccessRule is returned. When setting permissions on a registry key, a System.Security.AccessControl.RegistryAccessRule returned. When setting permissions on a private key, a System.Security.AccessControl.CryptoKeyAccessRule object is returned.

EXAMPLE 1

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.

EXAMPLE 2

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.

EXAMPLE 3

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.

EXAMPLE 4

Grant-Permission -Identity ENTERPRISE\Engineers -Permission FullControl -Path 'cert:\LocalMachine\My\1234567890ABCDEF1234567890ABCDEF12345678'

Grants the Enterprise's engineering group full control on the 1234567890ABCDEF1234567890ABCDEF12345678 certificate's private key/key container.