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 use the link below to submit your request around technical implementation support.
Please note:Please check our corporate site if this feature is available in your subscription plan.
Before you can start with the installation process, ensure to request the SharePoint Integration in the Beekeeper Marketplace.
The integration only works with drives from SharePoint sites. We cannot synchronise documents from a SharePoint page directly.
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.) In this step you will add the application permissions. You can give the application access to all the SharePoint sites with the Sites.Read.All permission or you can restrict the access to selected sites with Sites.Selected permission.
To give access to all sites, click on Application permissions and select the following permissions from the list and continue with step 8:
- Files
- Files.Read.All
- Sites
- Sites.Read.All
To give access to selected sites, click on Application permissions and select the following permissions from the list and continue with step 8:
- Files
- Files.Read.All
- Sites
- Sites.Selected
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
- 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 |
Giving Access to selected sites
If you chose to use the Sites.Selected permission in the section App Registration in Azure Active Directory > Option 1: ClientCredential Authentication Flow, you will need to give your client application access to the selected site(s). You will need to make the following API call(s) to add the reading permission to a specific site(s):
POST https://graph.microsoft.com/v1.0/sites/{site-collection-id}/permissions
Content-Type: application/json
{
"roles": ["read"],
"grantedToIdentities": [{
"application": {
"id": "id-of-your-azure-client-app",
"displayName": "display-name-of-your-azure-client-app"
}
}]
}
The site id is constructed with your SharePoint hostname (e.g. contoso.sharepoint.com), Site Collection (SPSite) ID, and Site (SPWeb) ID. The following is a breakdown of an example site ID:
Site ID: bkprpartners.sharepoint.com,a380090f-4863-460a-949b-7206f1094203,3a3e5a7f-8c14-4b89-9d92-faa64231b9dc
SharePoint hostname: bkprpartners.sharepoint.com
Site Collection (SPSite) ID: a380090f-4863-460a-949b-7206f1094203
Site (SPWeb) ID: 3a3e5a7f-8c14-4b89-9d92-faa64231b9dc
Example using Microsoft Graph Explorer:
You will need to make this API call for each site you want your client application to have access to. Once you have given your specific site(s) the required read permissions, you can continue with the remaining steps of the HC article.
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.
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.
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 use the link below to submit your request 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; Set as an empty string: "" if not used",
"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, Set as an empty string: "" if not used",
"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"
}
]
}
Comments
0 comments
Please sign in to leave a comment.