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}] [[-Type] {Allow | Deny}] [-Clear] [-PassThru] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]

Description

The Grant-Permission functions grants permissions to files, directories, registry keys, and certificate private key/key containers. It detects what you are setting permissions on by inspecting the path of the item. If the path is relative, it uses the current location to determine if file system, registry, or private keys permissions should be set.

The Permissions attribute should be a list of FileSystemRights, RegistryRights, or CryptoKeyRights, for files/directories, registry keys, and certificate private keys, respectively. 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])

Beginning with Carbon 2.0, permissions are only granted if they don't exist on an item (inherited permissions are ignored). If you always want to grant permissions, use the Force switch.

Before Carbon 2.0, this function returned any new/updated access rules set on Path. In Carbon 2.0 and later, use the PassThru switch to get an access rule object back (you'll always get one regardless if the permissions changed or not).

By default, permissions allowing access are granted. Beginning in Carbon 2.3.0, you can grant permissions denying access by passing Deny as the value of the Type parameter.

Directories and Registry Keys

When setting permissions on a container (directory/registry key) you can control inheritance and propagation flags using the ApplyTo parameter. This parameter is designed to hide the complexities of the Windows' inheritance and propagation flags. There are 13 possible combinations.

Given this tree

    C
   / \
  CC CL
 /  \
GC  GL

where

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 adapated 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
Type AccessControlType

The type of rule to apply, either Allow or Deny. The default is Allow, which will allow access to the item. The other option is Deny, which will deny access to the item.

This parameter was added in Carbon 2.3.0.

false false Allow
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.

EXAMPLE 5

Grant-Permission -Identity BORG\Locutus -Permission FullControl -Path 'C:\EngineRoom' -Type Deny

Demonstrates how to grant deny permissions on an objecy with the Type parameter.