Define where permissions apply with Set-Acl

Question

I'm trying to emulate in PowerShell what I typically do in the windows folder properties window available from: Folder properties → Secutity → Advanced → Permissions → Change Permissions...

In that GUI there are tick boxes for

• Include inheritable permissions from this object's parent
• Replace all child object permissions with inheritable permissions from this object - I believe corresponds to PropagationFlag = None

When you click the Add/Edit... button you have a drop down list with the following options, what InheritanceFlags correspond with each of them? I've filled in the ones I've found by experimentation

• This folder only - None
• This folder subfolders and files
• This folder and subfolders
• This folder and files
• subfolders and files only - ContainerInherit, ObjectInherit
• subfolders only - ContainerInherit
• files only - ObjectInherit

What flags correspond with the check box Apply these permissions to objects and/or containers within this container only?

I've also determined that these PropagationsFlags mean:

• InheritOnly (the ACE is propagated to all current child objects only if they are set to inherit)
• NoPropagateInherit (the ACE is not propagated to any current child objects)
• None (this ACE is propagated to ALL child objects overwriting what they had before and turns on their inheritance)

I'm wanting to find out how to add extra permissions for existing users/groups or add extra users/groups to the permissions of a folder and have that propagate with "This folder subfolders and files" but NOT "Replace all child object permissions with inheritable permissions from this object" in case there is a subfolder with other special permissions on it on purpose for a good reason, such as the symbolic link folders in user profiles.

The code I'm working with at the moment is below. Eventually I'm going to be using it on a lot of different folders on many computers in multiple domains including user profiles in c:\users\{username}

function check-permissions ( $folder ) {
    $GroupName = "Domain Admins"
    if ( -not (Test-Path -LiteralPath $folder) ) {
        Write-Output "Cannot find $folder"
    } else {
        ((get-acl -literalPath $folder).access).IdentityReference.Value |
            findstr /i ($env:USERDOMAIN + "\"+ $GroupName) |
            out-null
        $result = $?
        if ( -not $result ) {
            write-output ($folder + ": adding permissions")
            #adding new permissions
            $colRights = [System.Security.AccessControl.FileSystemRights]"FullControl" 
            $InheritanceFlag = [System.Security.AccessControl.InheritanceFlags]::ContainerInherit, [System.Security.AccessControl.InheritanceFlags]::ObjectInherit
            $PropagationFlag = [System.Security.AccessControl.PropagationFlags]::InheritOnly
            $objType =[System.Security.AccessControl.AccessControlType]::Allow
            $objUser = New-Object System.Security.Principal.NTAccount($env:USERDOMAIN + "\" + $GroupName)
            $objACE  = New-Object System.Security.AccessControl.FileSystemAccessRule ($objUser, $colRights, $InheritanceFlag, $PropagationFlag, $objType)
            # output the ACE
            $objACE | format-list *
            #$objACL = Get-Acl -literalPath $folder    # This gets the full security info but substitutes the different user as owner, which we don't want or it will overwrite the owner info with the wrong user when we use set-acl
            $objACL = (Get-Item -literalPath $folder).GetAccessControl('Access')
            if ( -not $? ) {
                Write-Output ("Failed to get permissions on: " + $folder)
            } else {
                $objACL.AddAccessRule($objACE)
                if ( $objACL ) { #objACL exists
                    #Set-ACL -literalPath ($folder) -AclObj $objACL  # This tries to set the owner too
                    [System.IO.Directory]::SetAccessControl($folder,$objACL) # This seems to work
                } else { # $objACL is null
                    write-output "Error developing new permissions object. Leaving folder permissions alone."
                }
            }
        } else {
            write-debug ($folder + ": Permissions OK")
        }
    }
}

check-permissions "c:\temp\test\a"

Answer 1

The "Apply To" value is defined by a combination of InheritanceFlags and PropagationFlags (which actually define how propagation is restricted). Here's an overview of which values produce which "Apply To" setting (ContainerInherit and ObjectInherit abbreviated to CI and OI respectively due to limited space):

Apply To                            Inheritance   Propagation
--------                            -----------   -----------
This folder only                    None          any
This folder, subfolders and files   CI, OI        None or NoPropagateInherit
This folder and subfolders          CI            None or NoPropagateInherit
This folder and files               OI            None or NoPropagateInherit
Subfolders and files only           CI, OI        InheritOnly
Subfolders only                     CI            InheritOnly
Files only                          OI            InheritOnly

For a more detailed description of propagation rules see here as mentioned by @CB. in the comments to your question.