Externally Sharing – GetSharingInformation REST API

Posted on by

Externally Sharing Series:

My last two blogs I have been explaining how to set up your tenant for External Sharing, and as a user how to share a document to an external user. At the end of my last blog post I explained how you can view which documents have been externally shared, by navigating to Site Usage and viewing the Externally Shared tab.

However, as stated previously, this section is flawed in a couple of ways.

  1. It relies on Search. Meaning that documents may not show up for a while.
  2. It only shows documents that have been externally shared, and the external user has viewed the file. This is because there is a flag (ViewableByExternalUser) on the file that gets updated, only after an external user has viewed the file, not when you have shared it.
  3. Following on from the last point, your site could have lots of documents externally shared, but you would never know if no one externally has viewed the file.
  4. Sharing of a folder will show up the folder in the list, (if external user goes directly to the folder). However, any items that are within the folder, which would also be externally shared, do not show up in this list. (Even if the external user has viewed the files)

If you had a content query webpart and want the same results to be brought back as it shows you in the ‘Shared externally’ tab you need to set your Search Query as follows:

Path:"<a href="https://examplesite.sharepoint.com/">https://examplesite.sharepoint.com/</a>" (IsDocument:"True" OR contentclass:"STS_ListItem") ViewableByExternalUsers=TRUE

GetSharingInformation REST API

The above ‘Externally Shared’ tab and search call, although it can bring back documents, it wasn’t what my client really wanted. They wanted to know straight away if the document was externally shared or not.

I emailed Stephen Rice (Product Manager for SharePoint and OneDrive for business) at Microsoft, and he said there wasn’t a current way of tagging the documents if they were externally shared at the time of sharing the document. The ViewableByExternalUsers is only updated when the user enters the document.

What I couldn’t understand was when I click the Info Panel for a document, if it was externally shared, it would state that the item was shared with guests. This was before an external user access the document.

Using Chrome network capture, I investigated what happens when the Info Panel loads up, and one call caught my attention.

https://tenant.sharepoint.com/_api/web/Lists(@a1)/GetItemById(@2)/GetSharingInformation?@a1='listguid'&@a2='itemID'&$Expand=permissionsInformation,pickerSettings

This call is made via a POST call.

Looking at the Preview response and digging further down into the results that returned, the permissionsInformation section contains all the Sharing links, and groups and users that the item is shared with.

permissionsInformation > links > results

Contains an array of link results. This includes internal sharing links, anonymous links and external links.

linkDetails

Important part of the linkDetails:

  • Created & CreatedBy – When the link was created and by who.
  • Expiration – Only used for anonymous links
  • HasExternalGuestInvitees –
    Indicates if any users that have been invited are external users
  • IsEditLink – Set to true for contribute, false for read
  • Invitations – See below
  • LinkKind – Enumeration (Microsoft.SharePoint.Client.SharingLinkKind)
    • 0 – Uninitialized
    • 1 – Direct
    • 2 – OrganizationView – People within ‘tenant’ Read
    • 3 – OrganizationEdit – People within ‘tenant’ Contribute
    • 4 – AnonymousView
    • 5 – AnonymousEdit
    • 6 – Flexible – Used in External Sharing with email address.
Invitations > results

The invitation sections gathers the information about the person who doing the inviting ‘InvitedBy‘ and who has been invited “invitee”. You also have the exact time and date when the invite was sent out.

linkMembers

I have discovered that the linkMembers only has values after the external user has visited the link.

permissionsInformation > links > results

The principals results are the groups and members that have access to the documents. If the external user has been previous added to your tenant via a site share, or document share before December 2017, then they will have an actual account in your tenant. Anything shared with them will show up here, instead of through the Shared Links. The Paul Matthews shown in the screenshot below is actually my personal email address and therefore an external user.


The role are:

  • 0 – None
  • 1 – Can View
  • 2 – Can Edit
  • 3 – Owner

principal

The principal contains the user or SP Group information. For users (principalType 1) this includes if they are external or not.

How to use this information?

The last section showed you all about the GetSharingInformation REST API call. It has to be done with a POST call, but apart from that, it does obtain all the Sharing Information in regard to that item. The only one thing I would say it is lacking is that if a SP Group that is assigned to that document had an external user in it. (For example, the members group, because you have externally shared the site) the isExternal flag on the principal of that group isn’t set to True.

Now knowing about GetSharingInformation REST API call I was able to create a SPFX field customizer. My next blog post will show you how I built the SPFX field customizer.