SharePoint Integration with the Document Library

Introduction

SharePoint is a web-based collaborative platform that integrates with Microsoft Office. SharePoint is primarily used as a document management/storage system and when integrated with Beekeeper, can allow your employees to instantly gain access through the Beekeeper App!

By using Beekeeper's Document Library, your employees can browse and view files of png, jpg, gif, pdf, xls, xslx, doc, docx, ppt, and pptx type that are 10MB or less. This integration is also built so employees are able to access and view content without a Microsoft license. Once configured by an administrator, employees can use their mobile device to directly view these files without having to download or save them locally!

Please note: In order to integrate SharePoint with the Document Library, you need to have the Operational Suite.

 

Overview

This article will walk through the steps required  to integrate from both the Microsoft side and the Beekeeper side. This process does require some passing of credentials between you and a Beekeeper CSM or CSE so please feel free to reach out for assistance at any point to your respective CSM or support@beekeeper.io.

 

This will be a walkthrough of 3 parts:

We will start with the authorizing a Beekeeper application within Azure Active Directory so that a connection can be established between your Beekeeper Document Library and SharePoint.

Then we will cover how to retrieve the correct ID's for your specific SharePoint Site. This will require some help from the Microsoft Graph Explorer which we will get into later.

Finally, we will configure your specific SharePoint Site to be readable by the Beekeeper platform so your employees can gain seamless access.

The three stages above are all geared toward generating the credentials required for a successful integration. Those credentials are summarized in the table below and this will act as a template for this integration.

 

Credential Template

Parameter	Value
Base URL
Application (client) ID
Directory (tenant) ID
App Registration Secret
DriveID
SiteID
DriveItemID
Beekeeper Folder ID

 

App Registration in Azure Active Directory

How it works

The SharePoint integration needs a token to call a web API on behalf of itself (not on behalf of a user). It uses the standard OAuth 2.0 client credentials grant.

Applications that acquire a token for their own identities:

• Are confidential client applications. These apps, given that they access resources independently of users, need to prove their identity. They're also rather sensitive apps. They need to be approved by the Azure Active Directory (Azure AD) tenant admins.
• Have registered a secret (application password or certificate) with Azure AD. This secret is passed in during the call to Azure AD to get a token.

 

App Setup Steps

1.) Login to your Microsoft 365 admin center and select Azure Active Directory from the main menu.

2.) Within Azure Directory admin center select Azure Active Directory from the main menu and App registrations from the sub menu.

3.) Click on the item New registration.

4.) Supply a unique name for the SharePoint integration. Select the option Accounts in any organizational directory (Any Azure AD directory - Multitenant) for Supported account types. No value is required for Redirect URI. Afterwards click on button Register.

5.) Remember the values for Application (client) ID and Directory (tenant) ID. These values are needed when configuring the integration within Beekeeper! Click on button View API permissions.

Use the Application (client) ID and the Directory (tenant) ID to fill out the credential template

Application (client) ID	8abb5250-fccf-4608-aa4a-c563d5aa0769
Directory (tenant) ID	9cadc3c2-7c83-4ca8-a506-73d2ee0e2cbc

6.) Click on button Add a permission and select Microsoft Graph API.

7.) Click on Application permissions and select the following permissions from the list:

- Files
    - Files.Read.All
    - Files.ReadWrite.All
- Sites
    - Sites.Read.All

8.) Afterwards click on button Grant admin consent for .... These settings ensure that no approval is needed by a particular user compared to normal OAuth flow.

9.) Select Certificates & secrets from the menu.

10.) Click on button New client secret. Add an optional description and specify when the secret should be expired.

11.) Afterwards copy the secret to the clipboard. When the dialog is changed the secret isn't accessible anymore! The secret is needed when configuring the integration within Beekeeper.

App Registration Secret

WKQ8h1MCW5z_c4JxsbfVAJ.m8~_3-P~x29

 

These 11 steps should have successfully gathered these first 3 fields.

Application (client) ID	8abb5250-fccf-4608-aa4a-c563d5aa0769
Directory (tenant) ID	9cadc3c2-7c83-4ca8-a506-73d2ee0e2cbc
App Registration Secret	WKQ8h1MCW5z_c4JxsbfVAJ.m8~_3-P~x29

 

Retrieving SharePoint Site ID's

How it works

Using your Office 360 login, your companies URL and intended SharePoint Site Name we will use the Microsoft Graph Explorer to retrieve the SiteID, FolderID and DriveItemID for your specific SharePoint site. We will be filling out these particular values in the credential template. 

 

Setup Steps

1.) To retrieve your Base URL, first log onto SharePoint and navigate to your homepage. Your Base URL will be the section of the URL that is highlighted.

Base URL

bkprpartners.sharepoint.com

 

2.) Open a web browser with the URL https://developer.microsoft.com/graph/graph-explorer to open the Graph Explorer and sign in.

3.) Obtain the SiteID and DriveID using the URL:

https://graph.microsoft.com/v1.0/sites/<URL>:/sites/<Site Name>?expand=drive

Note: Change the URL and the name of the requested site in the URL!

Example:

https://graph.microsoft.com/v1.0/sites/beekeeperpartners.sharepoint.com:/sites/Testsite-1?expand=drive

 

SiteID	bkprpartners.sharepoint.com,a380090f-4863-460a-949b-7206f1094203,3a3e5a7f-8c14-4b89-9d92-faa64231b9dc
DriveID	b!DwmAo2NICkaUm3IG8QlCA39aPjoUjIlLnZL6pkIxudw0J_Zc6UmsTJBHbfxUAw2j

 

4.) Obtain the DriveItemID using the DriveID you just acquired, and the path to the desired folder you wish to connect to integrate with Beekeeper.

Option 1 - Individual Folder: 

 

https://graph.microsoft.com/v1.0/drives/<DriveId>/root:/<Path to folder>

Note: Change the URL and the name of the requested site in the URL!

Example:

https://graph.microsoft.com/v1.0/drives/b!xrH_F8VeqkmhqXgtL7YFXJM_ynj7unNEjM43g93Vjg9htGz8yO8ITp2kCiTy0AJT/root:/sharepoint-test-data/Projekt-B

 

Option 2 - List of Folders:

https://graph.microsoft.com/v1.0/drives/<DriveId>/root/children

Example:

https://graph.microsoft.com/v1.0/drives/b!xrH_F8VeqkmhqXgtL7YFXJM_ynj7unNEjM43g93Vjg9htGz8yO8ITp2kCiTy0AJT/root/children

 

DriveItemID

01Q7BYIEJNQYI2B7VQPJCZYBJCMJTA4TXX

These 4 steps should help retrieve the 4 templated fields below.

Base URL	bkprpartners.shaerpoint.com
SiteID	bkprpartners.sharepoint.com,a380090f-4863-460a-949b-7206f1094203,3a3e5a7f-8c14-4b89-9d92-faa64231b9dc
DriveID	b!DwmAo2NICkaUm3IG8QlCA39aPjoUjIlLnZL6pkIxudw0J_Zc6UmsTJBHbfxUAw2j
DriveItemID	01Q7BYIEJNQYI2B7VQPJCZYBJCMJTA4TXX

 

 

Allow external sharing of SharePoint to the Beekeeper App

To do this, login to SharePoint admin center and select Active sites from the main menu. In the list of available sites select the needed site and click on button Sharing. Repeat this configuration step for every site needed. 

 

You've completed the app setup!

If you would like to go into more detail about app setup from the Microsoft side, see the resources below.

• Overview about Microsoft identity platform
• Details about app registration

 

Setup Within Beekeeper

This last step is where we will get the Beekeeper Folder ID and complete the credential template. Once the credential template is completed, reach out to your CSM/CSE or support@beekeeper.io to enable the connection.

1.) Purchase and Enable the SharePoint Integration

As this is a marketplace add-on, please reach out to your Customer Success Manager or support@beekeeper.io for pricing and enablement.

Create an Integration Folder

In the Dashboard, create an integration folder in your Document Library by clicking Add New and choosing Create Integration Folder.

3.) Set Up a Connection to SharePoint

This step will be performed once during the initial setup and involves choosing the directories you wish to make available to your employees. As this is an add-on marketplace application, please reach out to your Customer Success Manager or support@beekeeper.io to initially set up the connector. 

Once this is done, use the integration folder ID from the URL to select the desired folder.

4.) Set Access Permissions

Finally, configure the folder with your desired Name, Parent folder and Access settings.

 

5.) Get the Beekeeper Folder ID

Once you see the Integration Folder in you Document Library, click into the folder. In the URL, copy the value that comes after 'documents/' and add it into the Credentials Template.

 

Beekeeper Folder ID

ebecfec2-cd76-45ab-9325-cda697e45f58

 

Now that your Credential Template is complete, reach out to your CSM/CSE or support@beekeeper.io and they will generate a secure file drop for you to share the credentials with.

Please use the following example credentials to check the format of the ID's you gathered.

Example Completed Credential Template

Parameter	Value
Base URL	bkprpartners.sharepoint.com
Application (client) ID	8abb5250-fccf-4608-aa4a-c563d5aa0769
Directory (tenant) ID	9cadc3c2-7c83-4ca8-a506-73d2ee0e2cbc
App Registration Secret	WKQ8h1MCW5z_c4JxsbfVAJ.m8~_3-P~x29
DriveID	b!DwmAo2NICkaUm3IG8QlCA39aPjoUjIlLnZL6pkIxudw0J_Zc6UmsTJBHbfxUAw2j
SiteID	bkprpartners.sharepoint.com,a380090f-4863-460a-949b-7206f1094203,3a3e5a7f-8c14-4b89-9d92-faa64231b9dc
DriveItemID	01Q7BYIEJNQYI2B7VQPJCZYBJCMJTA4TXX
Beekeeper Folder ID	ebecfec2-cd76-45ab-9325-cda697e45f58

 

How to Use

1.) Access Integration Folder

Integration folders are visible by the SharePoint logo on the folder icon.

2.) Browse Content

All files and sub-folders of the connected SharePoint folder will be visible in the Dashboard of the Document Library. A SharePoint label in the navigation bar indicates that the files in the folder come from SharePoint. 

3.) Change Files

A link to the mirrored SharePoint folder helps you quickly make changes to the files and folders in SharePoint. Additionally you can change the configuration to link to another folder in SharePoint. Once set up, any change made to a document in SharePoint will be automatically updated for all employees accessing that document in Beekeeper.

 

FAQ's

1. Are all files mirrored?
   As most non-desk end-users don’t have wifi at their workplace, documents need to load fast and not drain a private data package too much. Due to this, the Document Library has a limit of 10MB per file. Larger files will not be mirrored in the Document Library. The supported file types are the following: png, jpg, gif, pdf, xls, xslx, doc, docx, ppt, pptx. This ensures that users can easily read the files on their mobile phone. Files that don't satisfy this condition will still appear but they will not be accessible.
   
   
2. Are the actual files from SharePoint copied over to Beekeeper?
   No. The integration makes the document visible using a link that goes straight to SharePoint. As the integration itself is connected to SharePoint, the user does not need a SharePoint license to be able to see content.
   
   
3. What is a Marketplace app?
   The Beekeeper Marketplace offers lots of different integrations to third party systems and other standalone extensions for Beekeeper. Each of these apps can be bought and installed separately to extend the value that Beekeeper brings to you.
   
   
4. Can I also sync files back to SharePoint?
   No. SharePoint remains the master system. This reduces the likelihood of duplicates appearing and makes it clear to everyone where documents should be managed.
   
   
5. What changes for the user? Do they see if a file or folder comes from SharePoint?End users will not see a difference between documents stored on Beekeeper or mirrored from SharePoint. But they will benefit from the fact that they’ll always have the latest version of the documents at their fingertips.
   
   
6. Why does the Beekeeper token need Read All/Write All access to SharePoint sites and files, when users can only read the documents put up on Beekeeper?
   We decided to go for a solution that would offload the files into Beekeeper with a temporary access, instead of passing them through our service directly. This is a much more efficient and faster way of implementing an integration, and especially because it is key for documents to be up to date, we decided to go for that route with the SharePoint Integration.
   
   In order for us to offload those files, we have to generate temporary URLs so these files can be listed in Beekeeper (the URLs are temporary, the listing then obviously remains for users to read those files). The Bot account in this configuration is actually more of an application we need to establish the connection to SharePoint. This Bot/application implements listing of folders or files in Beekeeper and makes them available through this temporary URL.
   
   The reason why this Bot/application therefore needs such high access rights is because the generation of temporary URLs is only possible with “Write All” access. That being said though, this specific Bot/application has been created specifically for the SharePoint Integration, is only usable with access to the Graph Library from Microsoft (in your account) and will not delete, create, move or access any other information than those you provide, as these operations have not even been implemented in the Bot/Application.
   
   
7. What steps are performed by the Customer Success Manager to set up the connector?
   The Customer Success Manager or Customer Success Engineer will set up the integration by using the SharePoint credentials to the site you would like to share folders and files from on Beekeeper. They will set it up using a JSON file containing the credentials. When the setup is complete, you can create the integration folders yourself.
   
   Our CSMs and CSEs undergo a special contractual obligation because they deal with sensitive customer information. As such, the credentials you share with them are protected within the realm of their responsibilities. That being said, the only right our Bot has is to get the information from the folders you select. We have not implemented any other possibility for the Bot to read or write information into SharePoint - the only operation we implemented in the integration is to generate temporary URLs.
   
   
8. Why do we have to grant Admin consent for Beekeeper in step 8?
   Our Bot needs to dock to Microsoft’s API so it can generate the temporary links as we implemented them for the integration. Since it can only do so with Write All access, we do not have any alternatives to this step here. However, as also mentioned above: the only “rights” (that are also mentioned by Microsoft on the screenshot on page 8) implemented on the Beekeeper side is for this bot to generate temporary URLs per file or folder - the Bot/application is not able to do anything else.
   
   From the Microsoft Graph API documentation: If you are calling the Microsoft Graph Security API from a custom or your own application, the Azure AD tenant admin must explicitly grant consent to your application. This is required both for application-level authorization and user delegated authorization.
   
   
9. Is there any reporting or logs easily available to tell when a document has been accessed and by whom within Beekeeper’s native document library and SharePoint shared document folders?
   As we don’t store the SharePoint shared folders and files on our servers, there is currently no possibility for any reporting or logs to tell when and by whom a document has been accessed within Beekeeper’s Document Library.
   
   
10. What technology and governance is used to generate the secure file drop sharing for the SharePoint credentials?
    We are using the secure cloud management software Box so you can share your SharePoint credentials with us. Box operates under strict data privacy and industry compliance requirements.
    
    
11. How are we allowed to use the SharePoint integration if Microsoft does not allow Multiplexing?
    The service Microsoft provides with SharePoint is to manage a folder structure and view said folder structure, the latter being offered by Beekeeper as well. With this SharePoint integration, we are transferring data you own (not Microsoft). Since we are not providing a frontend to use SharePoint features within the Beekeeper environment, multiplexing does not come into play.
    
    
12. We are releasing the DriveID with the integration, so wouldn’t that mean any third party could use a static URL to access any folder belonging to that drive?
    No. To get access to the SharePoint data (files and folders), a user needs to have an account with all the necessary permissions in SharePoint. Having the DriveID will not grant you automatic access to the files and folders.