SharePoint Integration Installation Guide

Overview

This article will walk through the steps required to integrate from both the Microsoft side and the Beekeeper side. This is a marketplace add-on that is free. If you require assistance with the configuration you can reach out to your Customer Success Manager for pricing information or support@beekeeper.io around technical implementation support.

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

Before you can start with the installation process, ensure to request the SharePoint Integration in the Beekeeper Marketplace. 

In the Beekeeper Dashboard, navigate to Extensions > Marketplace, type in 'Sharepoint' in the search bar, and click Request. Once the request has been made, the marketplace app will be installed by your Customer Success Manager. This is required for you to be able to complete the last section of this installation guide.

 

This will be a walkthrough of 4 parts:

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

There are two options to set up the connection between the SharePoint integration and a SharePoint
Server. These two options are:

• ClientCredential Authentication Flow
• UsernamePassword Authentication Flow

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

Next, 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 successful integration. Those credentials are summarised in the tables below and will act as a template for this integration.

Finally, we will cover how to configure the Marketplace app in Beekeeper to complete the establishment of the connection between your Beekeeper Document Library and SharePoint. 

 

Credential Template: ClientCredential Authentication Flow

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

 

Credential Template: UsernamePassword Authentication Flow

Parameter	Value
Base URL
Application (client) ID
Directory (tenant) ID
Username
Password
DriveID
SiteID
DriveItemID
Beekeeper Folder ID

 

 

App Registration in Azure Active Directory

Option 1: ClientCredential Authentication Flow

In this scenario, 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 a registered 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 the 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. Afterward, click on the 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 the 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 the 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 the 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 the 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

 

Option 2: UsernamePassword Authentication Flow

In this scenario, the SharePoint integration needs a token to call a web API on behalf of a user. It uses the standard OAuth 2.0 Resource Owner Password flow and will acquire a token on behalf of a user.

Using the UsernamePassword Authentication Flow is not recommended but as the SharePoint
integration is a daemon application with no direct user interface, and we want to make it access the
SharePoint Server on behalf of a user, we cannot avoid making use of it.

Applications that acquire a token on behalf of a user:

• Are confidential 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.
• Do not have a registered secret but make use of a username and password combination. This
  username and password will be passed to Azure AD during the call to get a token.
• The user needs to be an Azure AD user and must not have MFA active

App Setup Steps

First follow steps 1 to 6 of the ClientCredential Authentication Flow, listed above.

Then continue with step 7 from here:

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

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

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

9.) Allow public client flows. This setting is needed as we will make use of the UsernamePassword Authentication Flow where we are using a token (password) grant flow that doesn't use a redirect URI.

10.) Create a new user or choose an existing, which will be used for the authentication flow. Use the username and password to fill out the credential template.

Username	sharepoint-user@bkprpartners.onmicrosoft.com
Password	2A^,.XJuCg_#z[^K

These 10 steps should have successfully gathered these 4 fields.

Application (client) ID	8abb5250-fccf-4608-aa4a-c563d5aa0769
Directory (tenant) ID	9cadc3c2-7c83-4ca8-a506-73d2ee0e2cbc
Username	sharepoint-user@bkprpartners.onmicrosoft.com
Password	2A^,.XJuCg_#z[^K

 

Retrieving SharePoint Site ID's

How it works

Using your Office 360 login, your company 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/<Base URL>:/sites/<Site Name>?expand=drive

Note: Change the URL and the name of the requested site in the Base 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 DriveId and the Path to the folder 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

 

Please note: The access permissions to folders and its documents will need to be customised within Beekeeper. Therefore, if you would like to have customised access rights for different folders you will need to set up the respective permissions in the Beekeeper document library. As permissions can only be set on the highest level in the document library and all sub-folders will inherit these permissions, you will need to retrieve the DriveItemID for each folder you would like to set up within Beekeeper for which you want to customise the access permission.

 

Allow external sharing of SharePoint to the Beekeeper App

To do this, login to the SharePoint admin center and select Active sites from the main menu. In the list of available sites select the needed site and click on the 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 the app setup from the Microsoft side, see the resources below.

• Overview about Microsoft identity platform
• Details about app registration

 

Setup Within Beekeeper

Create an Integration Folder

Now we will get the Beekeeper Folder ID and complete the credential template. 

1.) In the Dashboard, click on Document Library.

2.) Click on Add new and choose Create integration folder.

 

3.) Name your folder and select the Locations and Groups that should have access to it.

4.) 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

 

Install and configure the Marketplace app

1.) Go to the Beekeeper dashboard and select the Sharepoint Integration marketplace app, which you should be able to find in the Requested / Installed tab

 

2.) After the app has been installed, click on Configuration. You should then see an editable configuration field.

Please reach out to support@beekeeper.io or to your Customer success manager if you can't see the configuration field.

3.) In the configuration field, add the information you have collected in the credential template as shown below:

Option 1: ClientCredential Authentication Flow

{
  "integrations": [
    {
      "url": "Insert the Base URL here",
      "secret": "Insert the App Registration secret here",
      "integrationArtifactId": "Insert the Beekeeper Folder ID here",
      "details": {
        "driveId": "Insert the DriveID here",
        "folderId": "Insert the DriveItemID here (optional)",
        "siteId": "Insert the SiteID here",
        "clientId": "Insert the Application (client) ID here",
        "tenantId": "Insert the Directory (tenant) ID here"
      },
      "integrationType": "io.beekeeper.sharepoint",
      "id": "Insert any unique ID here"
    }
  ]
}

 

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

Example Completed Credential Template: ClientCredential Authentication Flow

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

Example of configuration mapping:

{
  "integrations": [
    {
      "url": "bkprpartners.sharepoint.com",
      "secret": "WKQ8h1MCW5z_c4JxsbfVAJ.m8~_3-P~x29",
      "integrationArtifactId": "ebecfec2-cd76-45ab-9325-cda697e45f58",
      "details": {
        "driveId": "b!DwmAo2NICkaUm3IG8QlCA39aPjoUjIlLnZL6pkIxudw0J_Zc6UmsTJBHbfxUAw2j",
        "folderId": "01Q7BYIEJNQYI2B7VQPJCZYBJCMJTA4TXX",
        "siteId": "bkprpartners.sharepoint.com,a380090f-4863-460a-949b-7206f1094203,3a3e5a7f-8c14-4b89-9d92-faa64231b9dc",
        "clientId": "8abb5250-fccf-4608-aa4a-c563d5aa0769",
        "tenantId": "9cadc3c2-7c83-4ca8-a506-73d2ee0e2cbc"
      },
      "integrationType": "io.beekeeper.sharepoint",
      "id": "sp1"
    }
  ]
}

 

Option 2: UsernamePassword Authentication Flow

{
  "integrations": [
    {
      "url": "Insert the Base URL here",
      "secret": "Insert a random set of characters",
      "integrationArtifactId": "Insert the Beekeeper Folder ID here",
      "details": {
        "username": "Insert the Username here",
        "driveId": "Insert the DriveID here",
        "folderId": "Insert the DriveItemID here (optional)",
        "siteId": "Insert the SiteID here",
        "clientId": "Insert the Application (client) ID here",
        "tenantId": "Insert the Directory (tenant) ID here",
        "password": "Insert the Password here"
      },
      "integrationType": "io.beekeeper.sharepoint",
      "id": "Insert any unique ID here"
    }
  ]
}

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

Example Completed Credential Template: UsernamePassword Authentication Flow

Parameter	Value
Base URL	bkprpartners.sharepoint.com
Application (client) ID	8abb5250-fccf-4608-aa4a-c563d5aa0769
Directory (tenant) ID	9cadc3c2-7c83-4ca8-a506-73d2ee0e2cbc
Username	sharepoint-user@bkprpartners.onmicrosoft.com
Password	2A^,.XJuCg_#z[^K
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

{
  "integrations": [
    {
      "url": "bkprpartners.sharepoint.com",
      "secret": "ignored",
      "integrationArtifactId": "ebecfec2-cd76-45ab-9325-cda697e45f58",
      "details": {
        "username": "sharepoint-user@bkprpartners.onmicrosoft.com",
        "driveId": "b!DwmAo2NICkaUm3IG8QlCA39aPjoUjIlLnZL6pkIxudw0J_Zc6UmsTJBHbfxUAw2j",
        "folderId": "01Q7BYIEJNQYI2B7VQPJCZYBJCMJTA4TXX",
        "siteId": "bkprpartners.sharepoint.com,a380090f-4863-460a-949b-7206f1094203,3a3e5a7f-8c14-4b89-9d92-faa64231b9dc",
        "clientId": "8abb5250-fccf-4608-aa4a-c563d5aa0769",
        "tenantId": "9cadc3c2-7c83-4ca8-a506-73d2ee0e2cbc",
        "password": "2A^,.XJuCg_#z[^K"
      },
      "integrationType": "io.beekeeper.sharepoint",
      "id": "sp1"
    }
  ]
}

{
  "integrations": [
    {
      "url": "bkprpartners.sharepoint.com",
      "integrationArtifactId": "dd63c1f8-6a8c-4044-87bf-ae1640d2e526",
      "secret": "0Hj.Pf4ZAQ.hUy5ymrAtAlnj-xe._VOAb1",
      "details": {
        "driveId": "b!DwmAo2NICkaUm3IG8QlCA39aPjoUjIlLnZL6pkIxudw0J_Zc6UmsTJBHbfxUAw2j",
        "folderId": "01Q7BYIEJNQYI2B7VQPJCZYBJCMJTA4TXX",
        "siteId": "bkprpartners.sharepoint.com,a380090f-4863-460a-949b-7206f1094203,3a3e5a7f-8c14-4b89-9d92-faa64231b9dc",
        "clientId": "fc775b55-b9c9-44a7-9911-f3d5f47110e3",
        "tenantId": "9cadc3c2-7c83-4ca8-a506-73d2ee0e2cbc"
      },
      "integrationType": "io.beekeeper.sharepoint",
      "id": "sp1"
    },
    {
      "url": "bkprpartners.sharepoint.com",
      "integrationArtifactId": "different then above",
      "secret": "0Hj.Pf4ZAQ.hUy5ymrAtAlnj-xe._VOAb1",
      "details": {
        "driveId": "b!DwmAo2NICkaUm3IG8QlCA39aPjoUjIlLnZL6pkIxudw0J_Zc6UmsTJBHbfxUAw2j",
        "folderId": "different than above",
        "siteId": "bkprpartners.sharepoint.com,a380090f-4863-460a-949b-7206f1094203,3a3e5a7f-8c14-4b89-9d92-faa64231b9dc",
        "clientId": "fc775b55-b9c9-44a7-9911-f3d5f47110e3",
        "tenantId": "9cadc3c2-7c83-4ca8-a506-73d2ee0e2cbc"
      },
      "integrationType": "io.beekeeper.sharepoint",
      "id": "different Than Above"
    }
  ]
}