1. Introduction
With the Sharing Permissions dataset in Microsoft Graph Data Connect, you can see all the SharePoint permissions in your tenant. This covers both OneDrive and SharePoint Online permissions, whether they were granted directly or through sharing links, and whether they were granted to users or groups. Let’s take a closer look at what the Sharing Permissions dataset contains.
Before you proceed: Make sure you have read the blog post on SharePoint Data on Microsoft Graph Data Connect if you are new to the SharePoint datasets in MGDC.
2. The Hierarchy
In SharePoint, you can grant permissions to different kinds of objects: webs, lists, folders, or list items. To make sense of this, you need to know how SharePoint organizes these objects. Here is a quick explanation:
- Site Collection (site, SPSite) – Within a tenant, all items in SharePoint Online are broken into Site Collections. For developers, these map to the SPSite class. A site collection is sometimes simply referred to as a “site”. A tenant can have up to 2 million site collections.
- Web (site, subsite, SPWeb) – Every site collection must have a root web, also known as the top-level site. You can also have other webs under that root web, which are usually called subsites (up to 2,000 webs per site collection). For developers, these map to the SPWeb class. Most site collections have only one web (the root web) and no subsites.
- List (SPList) – Inside a web, the data is organized into Lists. For developers, these map to the SPList class. You can use lists to store structured data, like people working on a project, tasks to complete, games in a tournament, vinyl discs in a collection, artifacts in a museum or houses for sale. You can have many lists in a web (up to 2,000 lists per site collection, including all webs).
- Document Library (SPDocumentLibrary) – There is a special kind of list used specifically to store files in SharePoint. Those lists are commonly referred to as document libraries. For developers, these map to the SPDocumentLibrary class. All document libraries in SharePoint are lists, but not all lists in SharePoint are document libraries.
- Folders (SPFolder) – Inside a document library, your items can be organized using folders. For developers, these map to the SPFolder class. Folders are used to organize items in a document library. You can nest folders (have folders inside other folders). You may choose not to use folders at all, storing all items in the root of the document library. SharePoint stores folders as a special type of list item, but you can consider it as part of the hierarchy below the List and above the regular List Items.
- List Items (documents, files, SPListItem, SPFile) – Inside the list (or folder), you store list items. Each individual row in your list is a list item. You can also call them just items. For developers, these map to the SPListItem class. If the list is a document library, items are commonly referred to as documents or files. For developers, these map to the SPFile class. One list can have up to 30 million items (up to 300 thousand items recommended for better performance).
Notes:
- As you might have noticed, there is some confusion around the term “site” in SharePoint. It could refer to a “site collection” or to a “web”, depending on the context. In most cases, a site collection contains only a single web, in which case they refer to similar things. You will see the documentation mentions just “site” quite frequently. I try to avoid the more ambiguous term “site” and use the more precise terms “site collection” and “web”. For developers, the classes are named SPSite and SPWeb and there is no ambiguity.
- For developers, keep in mind that the SPFile and SPFolder objects do not have permissions assigned directly. The permissions go to the SPListItem that back them.
- There are some special files and folders that cannot be assigned permissions, like the Forms folder in a document library or the allitems.aspx file inside lists.
- A user’s OneDrive is a site collection. These site collections have a single root web with a “personal” template, including a document library where each user keeps their OneDrive folders and files.
3. Scopes
Permissions are granted for a specific scope. The scope starts with a specific object (web, list, folder, or list item) where the permissions should be applied and includes the objects under it, unless you create a more specific scope further down in the hierarchy. More about this in the “Inheritance” topic below.
Imagine that user U1 has Read permissions to item I3. The scope of that permission is at the item level, and it points to that single item. If we say that group G1 has Read permissions on list L1, the scope is that specific list and includes all the items it, unless you create scopes at the item level.
Each scope also gets an id that is unique within the site collection. If you grant different permissions to the same item, those permissions will use the same scope id.
4. Inheritance
An important concept in SharePoint permissions is inheritance, which is closely tied to the concept of scopes defined previously. Every object, by default, inherits the scope of its parent. So, when you grant permissions to a scope, every object in that scope gets those permissions.
From a user perspective, this looks like permission inheritance, but internally this is represented as permissions granted to a scope. It’s common to hear that you have “explicit permissions” for a parent object at the top of the scope and “implicit” or “inherited” permissions for child objects under that parent object.
The way SharePoint sees it, these are permissions granted to a single scope which includes both the parent and child objects. If you need to assign different permissions to a child object, you need to define a new unique scope at that level and grant unique permissions to that new scope.
For instance, if you grant user U1 Read permission on folder F1, user U1 also gets Read permissions on all items in folder F1 because they are all in the same scope. You might want to grant specific permissions for an item in that list. For instance, you could grant user U1 Edit permission for item I3 under folder F1. That creates a new unique scope at item I3 and that scope gets the permissions. You could also say that this breaks the inheritance for item I3.
On the SharePoint Sharing Permissions dataset, you will see two sets of permissions for this scenario: one for the scope at folder F1 and one for the scope at item I3. What users perceive is that there are “explicit permissions” for F1 and I3 and “inherited permissions” for all other items under F1.
Here is another example: if you grant Contribute permission to group G1 on web W1, all other objects in that scope get those permissions. The result is that group G1 gets Contribute permissions for all subsites, lists, folders, and list items in web W1, unless you create unique scopes somewhere under Web W1. For instance, you could create a new unique scope at list L1 under web W1 by granting Read permissions to group G1 on list L1. All items under list L1 will be in that same scope. What you will see in the Sharing Permissions dataset will be the permissions granted to the scope at web W1 and the scope at list L1.
It is important to mention that if you break inheritance by creating a new scope, you need to grant all required permissions to that new scope. For instance, assume you have a Contribute permission granted to group G1 on web W1. Then, you want to add Read permissions to user U1 on folder F1 under web W1. You should also include the Contribute permission to group G1 at the folder F1 scope, if you intend to keep group G1 permissions on that folder. The Contribute permission you granted to group G1 in the web W1 scope no longer applies to the folder F1 scope.
To help you when you stop inheritance by creating a new scope under an existing one, the modern SharePoint UX will copy the parent permissions to your new scope (we call this a permission pushdown). At that point, you can keep, remove, or change these copied permissions, as well as add new ones. See below a screenshot of the moment when you are about to stop inheriting permissions in the modern SharePoint UX:
The classic SharePoint UX has an option to copy permissions or not when stopping inheritance. It is generally easier to make the copy and then customize the permissions.
The Share dialog will also do a permission pushdown if that sharing action will be creating a new scope. This happens the first time you apply unique permissions to the object you are sharing.
Keep in mind that after you stop inheriting permissions by creating a new scope, the permissions copied to your new scope are not linked to the permissions from the parent scope. If you add more permissions to the parent scope in the future, the changes made to the parent permissions will NOT apply to the child scope (the point where you broke inheritance earlier).
5. Site Collection Administrators
Regular permissions are not granted at the site collection level. The highest level where you can grant regular permissions is the web. However, you can define a set of site collection administrators, which effectively gives them Full Control across the entire site collection. The site collection administrator’s privileges apply regardless of how you configure things at the lower levels.
To represent this in the SharePoint Sharing Permissions dataset, we added a special SiteAdmin item type. This was done to capture all permissions in this one dataset.
6. Role Definitions
To fully understand the Permissions dataset, it is important to know about role definitions. These are sets of permissions granted together in OneDrive and SharePoint.
Some common role definitions include:
- Full Control – Has full control. Can view, add, update, delete and customize any web, list and list item. Can manage permissions.
- Design – Can view, add, update, delete, approve, and customize lists and list items.
- Edit – Can view, add, update, and delete lists and list items. Note: the “Edit” permission given in the Share dialog actually maps to the “Contribute” role definition.
- Contribute – Can view, add, update, and delete list items.
- Review – Can view and review list items.
- Read – Can view and download list items.
- Restricted View – Can view list items, but not download them.
These role definitions are also referred to as permission levels.
7. Recipients (Users and Groups)
As we mentioned before, each permission specifies a recipient, which is the user or group where it applies. There are several types of users and groups that you can use when granting permissions.
Here are the types of users:
- Internal users – regular users from the tenant.
- External users – Microsoft Entra Id Guests – guest users from other domains. These users get a representation within your tenant’s Microsoft Entra Id (Azure Active Directory), with a name that contains #EXT#. For instance, if the external user email is sample.user@hotmail.com, the Microsoft Entra Id Guest will show in your domain as sample.user_hotmail.com#EXT#@yourdomain.onmicrosoft.com. You can see this type of guest user in your Azure Active Directory user list
- External users – SharePoint Guests – There is a second kind of guest user that lives only in SharePoint. These work in SharePoint via People Sharing Links. These users also get a special name with a URN:SPO:Guest# prefix. For instance, if the external user email is sample.user@hotmail.com, the SharePoint Guest user shows in the dataset as URN:SPO:Guest#sample.user@hotmail.com. These SharePoint Guests Users will not show in your Microsoft Entra Id (Azure Active Directory) user list.
- External users – Native Identity – external users from a domain configured in Microsoft Entra Id (Azure Active Directory) for native identity (also known as B2B direct connect). These users do not show in your Microsoft Entra Id (Azure Active Directory) since they live in another domain. These users are used only in site collections backing Teams Shared Channels.
Here are the types of groups:
- SharePoint groups – groups defined in the SharePoint site collection. SharePoint groups can contain users or Active Directory groups. You cannot nest SharePoint groups (you can’t add a SharePoint Group inside another SharePoint group).
- Microsoft Entra Id (Azure Active Directory) groups – security groups or Microsoft 365 groups defined in Microsoft Entra Id (Azure Active Directory). They can contain users or other Active Directory groups (nested groups).
- External Microsoft Entra Id (Azure Active Directory) groups – external groups from a domain configured in Microsoft Entra Id for native identity (also known as B2B direct connect). These groups do not show in your Microsoft Entra Id since they live in another domain. These groups are used only in site collections backing Teams Shared Channels.
There are also a few special group claims used when granting permissions:
- Everyone – All users (internal and external)
- Everyone Except External Users – All internal users (commonly called EEEU)
- SharePoint Administrator – Users configured as SharePoint administrator in Microsoft 365
- Global Administrator – Users configured as Global administrator in Microsoft 365
8. Sharing Links
In SharePoint Online, permissions can also be granted using a sharing link. This is a special URL that you can send to someone, typically via email or a Teams chat. Each sharing link gets a unique id.
Sharing links also must have a Link Scope. That is different from the sharing scope mentioned earlier.
Here are the types of Link Scope you can use:
- Specific People – This link can only be used by the people specified.
- Organization – This link can be used by anyone internal to the tenant (excludes Microsoft Entra Id Guests and SharePoint Guests).
- Anyone – This link can be used by anyone.
Note: There is a fourth type of “sharing link scope” called Existing Access. However, this link can only be used by people that already have access. These are not really “sharing” links, since they do not grant any access. The URL provided here is more of a convenient way to point to an object to which the user or group already has access.
For context, here is a screenshot of the SharePoint UX where you create a sharing link:
Note: The Sharing Permissions dataset includes columns for ShareCreatedBy, ShareCreatedTime, ShareLastModifiedBy, ShareLastModifiedTime and ShareExpirationTime. These properties only exist for permissions granted using sharing links.
9. Putting it all together
Now you can combine all these concepts to understand what’s in a SharePoint sharing permissions. You grant permissions (role definitions) for a scope (set of objects in the hierarchy) to a set of recipients (users or groups).
Here are the key properties for the objects in the dataset:
- ptenant – GUID that identifies the Office 365 tenant in Microsoft Entra Id.
- SiteId – GUID that identifies the SharePoint site (site collection).
- WebId – GUID that identifies the SharePoint web (subsite).
- ScopeId – GUID that identifies the SharePoint scope.
- LinkId – GUID for the share Link. Only shows if this is a sharing link.
- LinkScope – Scope for Sharing Link (Anyone, Organization, Specific People). Only shows if this is a sharing link.
- ItemType – The type of item being shared (SiteAdmin, Web, List, Folder, File).
- RoleDefinition – Sharing role or permission (Read, Contribute, Full Control, etc.)
- SharedWith – Object array with one entry for every sharing recipient.
- SharedWith, Type – Type of recipient (Internal, External, SecurityGroup, SharePointGroup).
- SharedWith, Name – Name of the sharing recipient.
- SharedWith, EmailAddress – Email of sharing recipient. It will not show for SharePoint groups or special security groups.
Note: For a complete schema of the SharePoint Sharing Permissions dataset in Microsoft Graph Data Connect, review the SharePoint Sharing Permissions dataset schema.
10. Resources
Finally, here are more learning resources on these topics:
- Overview of sites and site collections in SharePoint Server
- Overview of site permissions in SharePoint Server
- User permissions and permission levels in SharePoint Server
- Sharing and permissions in the SharePoint modern experience
- SharePoint limits – Service Descriptions
- API Reference – Microsoft SharePoint namespace
- Sharing files, folders, and list items