When to use OneDrive vs Sharepoint
A OneDrive connection is user-level only. If you want access to all users' OneDrive data, you should connect through SharePoint as a super admin.
Data structure
Folders, Files, and Permissions
Merge syncs files, folders, and their permissions (sometimes called Access Control Lists or ACLs) from two main locations in OneDrive:
My files
All files and folders stored in the authenticated user's OneDrive can be found here.
Shared
Files and folders shared with the authenticated user and shared by the authenticated user are found here. Merge only syncs items shared with the authenticated user from this location as files shared by the authenticated user are already synced through "My files".
Checksums
The file checksum object stores a OneDrive-generated checksum value, providing a way to confirm if file contents have changed. This field is mapped from the OneDrive API, not generated by Merge.
Only files in the "My files" folder will have a checksum. OneDrive does not return checksum information for files shared with the authenticated user.
In certain cases, OneDrive may not generate a checksum value or may assign a generic value. An example of a generic checksum value is:
"checksum": {
"type": "quickXor",
"content_hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAA="
},
Users
Users are individuals with access to files and folders. They can be associated through Groups and granted access to files/folders/drives at the group level.
Users can also be associated with a domain (e.g. "@merge.dev"). Microsoft does not support the whitelisting of external domains, meaning there is typically only one domain-level permission for a Microsoft instance. This will show up as a permission of type COMPANY in the Merge API.
Groups
Microsoft Office has several types of groups. Merge supports Azure AD groups and Microsoft 365 Groups, which are the modern standards for managing groups of users in Microsoft Office. Merge syncs all Azure AD groups and Microsoft 365 Groups in the Microsoft Office environment, as all can be used in ACLs when sharing files/folders on the end user's OneDrive.
Ingestion
Sync cadence
OneDrive's API capabilities differ significantly based on the file's location and ownership. Files in OneDrive fall into two primary categories:
Owned Files: These are files directly owned by the connected user. Owned files support timestamp filtering, enabling us to efficiently retrieve only updated information. This functionality aligns with behaviors observed in SharePoint and Google Drive, allowing for faster syncs and webhook support. The sync speeds are set to 5 minutes for these models.
Shared Files: These are files shared with, but not owned by, the connected user. Shared files do not support timestamp filtering, which necessitates a complete resync each time new data is required. Additionally, the OneDrive API does not inherently notify when shared files have been deleted or unshared. The sync speeds for these models are listed in this table.
Due to these limitations, we cannot increase sync frequencies significantly for shared files in OneDrive. However, we may require future adjustments as we gather more data. The optimal sync frequency will vary considerably depending on individual customers' OneDrive instance sizes and their ratios of owned to shared files.
Webhooks
Merge supports third-party webhooks for OneDrive so near real-time updates can be retrieved! Due to limitations with Microsoft Graph's subscription functionality, OneDrive third-party webhooks only detect updates in the "My files" location and do not capture "Shared with me" updates.
Merge will capture the following updates to items in the "My files" location:
New files and folders
Updated files and folders
Deleted files and folders
Files and folders newly shared with users
OneDrive does not send webhooks for the updates below, and therefore, Merge does not support third-party webhooks for them. These events will be picked up with the normal syncing processes between Mergre and OneDrive.
Updating a user's permissions to a file
Remove a user's permissions to a file
Mime Types
OneDrive allows two possible export types on their Graph API. Merge allows passing a mime_type query parameter for our /direct-download endpoint only. The proxy download endpoint will return the default OneDrive export type and does not currently accept the mime_type parameter.
Download mime type | Description | Supported native file type |
Converts the item into PDF format. | csv, doc, docx, odp, ods, odt, pot, potm, potx, pps, ppsx, ppsxm, ppt, pptm, pptx, rtf, xls, xlsx | |
html | Converts the item into HTML format. | loop, fluid, wbtx |
Authentication
Personal vs Business
Microsoft supports two different OneDrive account types: Personal and Business. Merge currently only supports connections to Business accounts.
Admin consent
To sync all user and group information across the authenticated user's Microsoft tenant, Merge must request the Group.Read.All, GroupMember.Read.All, and User.Read.All permissions. These permissions require admin consent. Any non-admins will not be able to authenticate the connection until an admin has granted consent.
If admin consent has not yet been given, the end user will see one of two options after signing in through the OAuth flow (full details in this Microsoft guide):
A notification that admin consent is required and a message prompting the user to reach out to an admin.
This signals that the end user's Microsoft tenant has not yet configured the admin consent workflow, and the user will have to reach out to an admin of the Microsoft tenant.
A notice that approval is required and the ability to request approval directly in the auth flow.
This form allows the user to submit a request for admin consent directly in the auth flow.
If you know you will be linking multiple non-admin users in one Microsoft tenant, you may want to consider having an admin grant tenant-wide admin consent to your application. For instructions on how to grant tenant-wide admin consent, see this article from Microsoft.
Supported authentication types
Read only
Merge will launch a OneDrive OAuth flow, which will prompt your customer for their username and password.
The authenticating user can be anyone with valid OneDrive login credentials.
Merge will only have access to the authenticated users OneDrive, as well as shared drives and files explicitly shared with them.
Read & write
Merge will launch a OneDrive OAuth flow, which will prompt your customer for their username and password.
Merge will have access to all user files and folders.
This authentication method is only recommended if your application needs to POST files back to OneDrive.