From 375354b609491b00af3b520484d125b86655a872 Mon Sep 17 00:00:00 2001
From: Corbin <corbin@cbarts.net>
Date: Mon, 6 Apr 2026 08:31:13 -0400
Subject: [PATCH] Add Set-PnPFolderAcl

---
 m365/Set-PnPFolderAcl.ps1 | 116 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 m365/Set-PnPFolderAcl.ps1

diff --git a/m365/Set-PnPFolderAcl.ps1 b/m365/Set-PnPFolderAcl.ps1
new file mode 100644
index 0000000..b275a60
--- /dev/null
+++ b/m365/Set-PnPFolderAcl.ps1
@@ -0,0 +1,116 @@
+[CmdletBinding()]
+param(
+	[Parameter(Mandatory=$true)]
+	[string]$Name,
+	[Parameter(Mandatory=$true)]
+	[string]$List = 'Shared Documents',
+	[Parameter(Mandatory=$true)]
+	[string]$Owner,
+	[Parameter()]
+	[array]$Acl
+)
+
+<#
+.SYNOPSIS
+	Sets permissions on a folder in a SharePoint document library.
+.DESCRIPTION
+	This script breaks permission inheritance on a specified folder in a SharePoint document library and assigns permissions to a specified owner group and additional groups defined in the ACL parameter.
+.PARAMETER Name
+	The name of the folder to set permissions on.
+.PARAMETER List
+	The name of the document library containing the folder. Default is 'Shared Documents'.
+.PARAMETER Owner
+	The name of the SharePoint group to assign as the owner of the folder with 'Full Control' permissions.
+.PARAMETER Acl
+	An array of objects defining additional groups and their permissions to assign to the folder. Each object should have a 'DisplayName' property for the group name and a 'Role' property for the permission level (e.g., 'Read', 'Edit').
+.EXAMPLE
+	$Acl = @(
+		@{ DisplayName = "SG-ADMIN-AdvocateFloats-Dynamic"; Role = "Edit" },
+		@{ DisplayName = "SG-ADMIN-AdvocateManagers-Dynamic"; Role = "Edit" }
+	)
+	.\Set-PnPFolderAcl.ps1 -Name "ProjectX" -List "Shared Documents" -Owner "Project Owners" -Acl $Acl
+#>
+
+<#
+.SYNOPSIS
+	Tests if a PnP Group exists.
+.DESCRIPTION
+	This function tests if a PnP Group exists in the current SharePoint site.
+.PARAMETER Identity
+	The identity of the group to test.
+.EXAMPLE
+	Test-PnPGroup -Identity "MyGroup"
+#>
+function Test-PnPGroup {
+	param(
+		[string]$Identity
+	)
+
+	try {
+		Get-PnPGroup -Identity $Identity -ErrorAction Stop | Out-Null
+		return $true
+	} catch {
+		return $false
+	}
+}
+
+<#
+.SYNOPSIS
+	Tests if an Entra ID Group exists and PnP can resolve it.
+.DESCRIPTION
+	This function tests if a Entra ID Group exists and can be resolved by PnP.
+.PARAMETER Identity
+	The identity of the group to test.
+.EXAMPLE
+	Test-EntraIdGroup -Identity "MyGroup"
+#>
+function Test-EntraIdGroup {
+	param(
+		[string]$Identity
+	)
+
+	try {
+		Get-PnPEntraIdGroup -Identity $Identity -ErrorAction Stop | Out-Null
+		return $true
+	} catch {
+		return $false
+	}
+}
+
+# Validate that we are connected to a SharePoint site and that the specified list and owner group exist
+if (-not (Get-PnPContext)) {
+	Write-Error "Not connected to a SharePoint site. Please connect using Connect-PnPOnline before running this script."
+	exit 1
+}
+if (-not (Get-PnPList -Identity $List -ErrorAction SilentlyContinue)) {
+	Write-Error "The specified list '$List' does not exist on the current site."
+	exit 1
+}
+if (-not (Test-PnPGroup -Identity $Owner)) {
+	Write-Error "The specified owner group '$Owner' does not exist on the current site."
+	exit 1
+}
+
+# Warning if no ACL entries are provided, as this will result in the folder having no permissions assigned
+if ($Acl.Count -eq 0) {
+	Write-Warning "No ACL entries provided. The folder will have no permissions assigned."
+}
+
+
+# Break inheritance on the location folder and set ownership
+Write-Host "Breaking permission inheritance for folder '$List/$Name'."
+Write-Host "Assigning 'Full Control' permissions to SharePoint group '$Owner' for folder '$List/$Name'."
+Set-PnPFolderPermission -List $List -Identity "$List/$Name" -Group $Owner -AddRole 'Full Control' -ClearExisting
+
+foreach ($Group in $Acl) {
+	if (Test-PnPGroup $Group.DisplayName) {
+		Write-Host "Assigning '$($Group.Role)' permissions to SharePoint group '$($Group.DisplayName)' for folder '$List/$Name'."
+		Set-PnPFolderPermission -List $List -Identity "$List/$Name" -Group $Group.DisplayName -AddRole $Group.Role
+	} elseif (Test-EntraIdGroup $Group.DisplayName) {
+		Write-Host "Assigning '$($Group.Role)' permissions to Entra ID group '$($Group.DisplayName)' for folder '$List/$Name'."
+		Set-PnPFolderPermission -List $List -Identity "$List/$Name" -User $Group.DisplayName -AddRole $Group.Role
+	} else {
+		Write-Warning "Group '$($Group.DisplayName)' does not exist. Skipping permission assignment."
+		continue
+	}
+}