This script updates permissions for a SharePoint folder. In case of Sharepoint Online the permissions are added to the existing ones. To use it in Adaxes, you can add the script to a business rule, custom command or scheduled task using the Run a program or PowerShell script action.
Script 1: SharePoint on-premise
Parameters:
- $sharePointServer - Specifies the NetBIOS name of the computer where the SharePoint Sever is homed.
- $webApplicationURL - Specifies the URL of the SharePoint web application.
- $folderPath - Specifies the path to the folder for which to update the access permissions.
Note: You can use value references (e.g. %name%) to use properties of the object on which the script is executed as a part of the folder path. For example, if you specify Shared Documents/Folder A/%name% and execute the script on a user whose name is John Doe, the resulting path will be Shared Documents/Folder A/John Doe.
- $stopInheritablePermissions - Specifies whether to stop inheriting permissions from the parent.
- $securityItems - Specifies the permissions to set.
You can specify custom security settings for users, Active Directory groups or SharePoint groups. Format:
"DOMAIN\username"="RoleType";"DOMAIN\groupname"="RoleType";"SharePointGroupName"="RoleType"
Default role types: Administrator, Contributor, Reader, WebDesigner.
PowerShell
$sharePointServer = "SharePointServer" # TODO: modify me
$webApplicationURL = "http://$sharePointServer/sites/MySite" # TODO: modify me
$folderPath = "Shared Documents/Folder A/%name%" # TODO: modify me
$stopInheritablePermissions = $True # TODO: modify me. Specify $False to inherits permissions from the parent or $True to stop inheritance
$securityItems = @{"EXAMPLE\Administrator"="Administrator";"SharePointDesigners"="WebDesigner"} # TODO: modify me
# Connect to the SharePoint Server
$session = New-PSSession $sharePointServer -Authentication Kerberos
$result = Invoke-Command -Session $session -ArgumentList $webApplicationURL, $folderPath, $newFolderPath, $stopInheritablePermissions, $securityItems -ScriptBlock {
param($webApplicationURL, $folderPath, $newFolderPath, $stopInheritablePermissions, $securityItems)
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint") | Out-Null
# Open the web application
$site = New-Object Microsoft.SharePoint.SPSite("$webApplicationURL")
$web = $site.OpenWeb();
# Access the folder
$folder = $web.GetFolder($folderPath)
if ($folder.Exists)
{
$folder = $folder.Item
if ($stopInheritablePermissions)
{
$folder.BreakRoleInheritance($true)
$userFolderRoleAssignments = $folder.RoleAssignments
$userFolderRoleAssignmentsCount = $userFolderRoleAssignments.Count
for ($i = $userFolderRoleAssignmentsCount-1; $i -ge 0; $i--)
{
$folder.RoleAssignments.Remove($i)
}
# Save changes
$folder.Update()
}
# Set permissions
$errorInfo = $NULL
if ($securityItems -ne $NULL)
{
$folder.BreakRoleInheritance($true)
foreach ($objectName in $securityItems.Keys)
{
$roleTypeName = $securityItems[$objectName]
try
{
$roleDefinition = $web.RoleDefinitions.GetByType($roleTypeName)
}
catch
{
$errorInfo += $objectName + "; "
continue
}
if ($web.SiteGroups[$objectName] -ne $NULL)
{
$customRoleAssignment = New-Object Microsoft.SharePoint.SPRoleAssignment($web.SiteGroups[$objectName])
}
else
{
$customRoleAssignment = New-Object Microsoft.SharePoint.SPRoleAssignment($objectName,$null,$null,$null)
}
$customRoleAssignment.RoleDefinitionBindings.Add($roleDefinition)
$folder.RoleAssignments.Add($customRoleAssignment)
}
# Save changes
$folder.Update()
}
return $errorInfo
}
}
Remove-PSSession -Session $session
# If there was an error when changing permissions, show the error
if ($errorInfo -ne $NULL)
{
$Context.LogMessage("Failed to set folder permissions for " + $result + " because the specified Role Type was not found on the server.", "Warning")
}
Script 2: SharePoint Online
For the script to work you will need to install a certificate for connection to SharePoint Online on the computer where Adaxes service runs. To do so:
- Create a certificate using the New-PnPAzureCertificate cmdlet.
- Assign the certificate to the Azure application whose credentials were used to register your Microsoft 365 tenant in Adaxes.
- Grant Azure application access to SharePoint (i.e. Sites.FullControl.All).
- Install the certificate on the computer where Adaxes service runs.
Parameters:
- $certificateThumbprint - Specifies the Thumbprint of the certificate that will be used to connect to SharePoint Online. For information on how to retrieve the Thumbprint, see How to: Retrieve the Thumbprint of a Certificate.
- $tenantName - Specifies the name of the Microsoft 365 tenant associated with the user. For information on how to check the tenant, see View Microsoft 365 tenant for a user.
- $webApplicationURL - Specifies the URL of the SharePoint web application.
- $list - Specifies the name of the list the folder belongs to.
- $folderPath - Specifies the path to the folder for which to update the access permissions.
Note: You can use value references (e.g. %name%) to use properties of the object on which the script is executed as a part of the folder path. For example, if you specify Shared Documents/Folder A/%name% and execute the script on a user whose name is John Doe, the resulting path will be Shared Documents/Folder A/John Doe.
- $customSecurityItems - Specifies the permissions to set.
PowerShell
$certificateThumbprint = "9BCE7405DD63FD8DE7486FDD32D111667197BB8E" # TODO: modify me
$tenantName = "MyTenant" # TOOD: modify me
$webApplicationURL = "https://$tenantName.sharepoint.com/sites/MySite" # TODO: modify me
$list = "Shared Documents" # TODO: modify me
$folderPath = "$list/Folder A/%name%" # TODO: modify me
$customSecurityItems = @{"MyAdGroup 1" = "Full Control"; "MyAdGroup 2" = "Design"; "MyUser@company.com" = "Edit"} # TODO: Specify custom security for users (other than the target user), groups
# "User or AD Group name"="RoleType";
# Default role types: Full Control, Design, Edit, Contribute, Read, Restricted View.
# Specify $customSecurityItems = $NULL for default (inherited) permissions
# Connecto to SharePoint Online
$tenant = $Context.CloudServices.GetO365Tenant()
$credential = $tenant.GetCredential()
try
{
$connection = Connect-PnPOnline -Url $webApplicationURL -ClientId $credential.AppId -Thumbprint $certificateThumbprint -Tenant "$tenantName`.onmicrosoft.com" -ReturnConnection
# Set custom permissions
if ($customSecurityItems -ne $NULL)
{
foreach ($objectName in $customSecurityItems.Keys)
{
Set-PnPFolderPermission -List $list -Identity $folderPath -User $objectName -AddRole $customSecurityItems[$objectName]
}
}
else
{
Set-PnPFolderPermission -List $list -Identity $folderPath -InheritPermissions
}
}
finally
{
# Close the connection and release resources
if ($connection) { Disconnect-PnPOnline -Connection $connection }
}
Hello,
We added a script for SharePOint Online. It can be executed in Business Rules, Custom Commands and Scheduled tasks configured for the User object type.
I get this error
You cannot call a method on a null-valued expression.
At line:44 char:5
+ $Context.LogMessage("Folder does not exist", "Error")
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ CategoryInfo : InvalidOperation: (:) [], RuntimeException
+ FullyQualifiedErrorId : InvokeMethodOnNull
any ideas?
As we mentioned previously, the script can only be executed in Adaxes business rules, custom commands and scheduled tasks. It uses the predefined variable $Context and thus will never work in Windows PowerShell.