How to Use Scoped Graph Permissions to Access SharePoint Files

Limit App Access to Specific Files and Folders in a SharePoint or OneDrive Site

Following on from the discussion about using RBAC for Applications to limit apps from being able to send email fromany Excange Online mailbox, let’s discuss how SharePoint Online and OneDrive for Business can limit app access to files and lists. In another article, I describe how to use the Sites.Selected permission to limit app access to sites. Being able to grant permission to apps to access specific sites is a fundamental control similar to the mailbox-level control exerted by RBAC for Applications.

More so than mailboxes, SharePoint Online sites can store confidential information in files and lists, and SharePoint has always offered the ability to restrict access at the item or file level. As we’ll discover, tenants can employ much the same technique to create a delegated scope to limit app access to individual lists, list items, and files. Some practical examples always help, and that’s what’s covered in this primer.

Graph Permissions for Granular Access to SharePoint Content

A set of Graph permissions to limit access to SharePoint and OneDrive information is at the heart of the discussion. The previous article describes how to use the Sites.Selected permission, The focus now switches to three Graph delegated scoped permissions to control app access with different scopes within a site. They are delegated by an administrator to an app, and they are scoped to specific files, lists, or list items. The permissions are:

• Files.SelectedOperations.Selected: Manage app access to files or folders within a document library. Access granted to a folder allows access to all files within the folder.
• Lists.SelectedOperations.Selected: Manage app access for a list.
• ListItems.SelectedOperations.Selected: Manage app access for more or more list items.

At a technical level, document libraries are lists and files are items within those lists. Other lists store different kinds of data, not all of which are files, and that’s why separate permissions exist for files and list items.

Three-Steps to Scoped Access

Creating a delegated scope to allow app-only access to specific resources requires three steps:

1. Assign the required Graph permission to the app. Figure 1 shows an app registration with consent to use the four limited scope permissions. Having consent for the Graph permissions doesn’t matter because the permissions are useless without scoped access being granted to files, lists, or list items. Consent is for application permissions to allow app-only access to files and folders. Delegated scoped permissions are also supported for interactive sessions.
2. Grant access to the app by creating an entry in the permissions endpoint for the target resource.
3. Authenticate the app with Entra ID and make sure that the access token contains the correct Graph permission.

I use cmdlets from V2.35.1 of the Microsoft Graph PowerShell SDK in the following examples.

Adding Scoped Access to Files and Folders in a Selected Site

The New-MgDriveItemPermission cmdlet adds a scoped permission to a drive item (file or folder). In this example, we’ll limit access to the Critical Info folder. To add the scoped permission, we need to know the identifiers for the drive (document library) and drive item (folder). Using an interactive session with consent for Sites.FullControl.All permission and holding the SharePoint administrator role allows us to access the data and fetch the identifiers. This code:

• Gets the default document library.
• Gets items in the root folder.
• Extracts details of the Critical Info folder.

# Find default document library
$DefaultDocumentLibrary = Get-MgSiteDrive -All -SiteId $SiteId | Where-Object {$_.Name -eq 'Documents'}
# Get items in the root folder
[array]$Data = Get-MgDriveItemChild -DriveId $DefaultDocumentLibrary.Id -DriveItemId "root" -All
# Find the target folder to gramt permission for
[array]$Folders = $Data | Where-Object {$_.folder.childcount -gt 0} | Sort-Object Name
$CriticalFolder = $Folders | Where-Object {$_.Name -eq "Critical Info"}
# Just to test, see what files are in the folder
[array]$CriticalFolderFiles = Get-MgDriveItemChild -DriveId $DefaultDocumentLibrary.Id -DriveItemId $CriticalFolder.Id -All

The identifier for the app that will access the folder is also needed. Once that information is secured, we can create the request body to use with the New-MgDriveItemPermission cmdlet to add the scoped permission:

# Get application identifier
$AppId = (Get-MgApplication -Filter "displayName eq 'SharePoint Limited Access app'").AppId 

# Define role to assign
$Role = "write"

# Create request body to request role for the application
$Requestbody = @{
  roles     = @($Role)
  grantedTo = @{
    application = @{
      id = $AppId
    }
  }
}

# Attempt to add the permission
$Status = New-MgDriveItemPermission -DriveId $DefaultDocumentLibrary.Id -DriveItemId $CriticalFolder.Id -BodyParameter $RequestBody
If ($Status) {
   Write-Host ("{0} permission granted for {1}" -f $Role, $CriticalFolder.Name)
}

Repeat the process to add permissions for as many folders or individual files as required. A difference in the request bodies used to assign permissions for use with Sites.Selected and Files.SelectedOperations.Selected is that the file permission uses the older grantedTo property as its assignment target while the site permission uses the newer grantedToIdentitiesV2 property. Microsoft is moving away from grantedTo to grantedToIdentitiesV2 for permission assignments, so this might change in time.

After the permission is granted, the app can navigate to the folder and work with the items in the folder using the same commands to find the document library and target folder as shown above. The app doesn’t have the Graph permission to search for the target site, so this value might have to be hard coded. The app cannot see any other document libraries in the site or any other folders in the document library. SharePoint masks this information from the app when it returns data in response to app requests.

Granular App Access to Files and Folders

The Files.SelectedOperations.Selected permission is an effective method of granting granular access to files and folders in a SharePoint Online or OneDrive for Business document library. For more information about using delegated scopes, see the Microsoft documentation. This script shows how to retrieve document libraries, files, and folders to create a report of SharePoint Online files. It might help you understand how to navigate site contents.

---

Insight like this doesn’t come easily. You’ve got to know the technology and understand how to look behind the scenes. Benefit from the knowledge and experience of the Office 365 for IT Pros team by subscribing to the best eBook covering Office 365 and the wider Microsoft 365 ecosystem.