Managing Document Access & Permissions for Content Sources
editManaging Document Access & Permissions for Content Sources
editThe following guide applies to first-party content sources. For more information on custom sources, visit the Document permissions for custom sources guide.
Workplace Search can associate its notion of a user to a third-party’s, and in doing so limit access to documents. If a person has certain permissions on Google Drive, for example, you can associate their Google Drive user via the External Identities API reference to their Workplace Search user. When their Workplace Search user tries to search, their permissions are honoured. As a result, they will see documents they can see and not see documents which they cannot.
This guide will walk you through how to do so with each supporting third-party.
First-party content sources
editDocument permission synchronization can be enabled for sources when connecting an instance to Workplace Search.
We support document permission synchronization within:
- Document-level permissions for Google: Google Drive
- Document-level permissions for Microsoft: SharePoint Online & OneDrive
Once activated during connector setup, document access for a user must be mapped to Workplace Search’s notion of that user. Use the External Identities API reference, to provide the external source_user_id
and link it to its associated Workplace Search user
:
{ "source_user_id": "john.doe@example.com", "user": "john.doe" }
The above example would link Google’s notion of john.doe@example.com
and Workplace Search’s notion of john.doe
as the same entity. Permissions are then synchronized between these entities, restricting or enabling access to documents. Different content sources will expose their notion of a user in different ways.
Document-level permissions for Google
editApplies to Google Drive.
Google attributes an id
to each user.
The id
is a string, a person’s email: personal.person@example.com
You can retrieve a comma separated list in CSV format from Google. Read Google documentation. An example query to the External Identities API reference that takes a person’s Google’s id
and associates it with their Workplace Search user looks as follows:
curl -X POST http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities \ -H "Authorization: Bearer [ACCESS_TOKEN]" \ -H "Content-Type: application/json" \ -d '{ "user": "personal.person", "source_user_id": "personal.person@example.com" }'
{ "user": "personal.person", "source_user_id": "personal.person@example.com" }
Document-level permissions for Microsoft
editApplies to: OneDrive and SharePoint Online
Workplace Search can synchronize with Microsoft Office 365 Groups.
Microsoft attributes an Id
to each user.
The Id
is a string, it looks something like this: 32ad7bda-3de1-4a77-ee97-f3476c2cf58d
.
Associate the Id
string with a Workplace Search user using the External Identities API reference. You can get a list of user ``Id``s by visiting the Users section of Microsoft Admin. From there, select the user’s you would like to map, then click Export Users.
An example query to the External Identities API reference that takes a person’s Microsoft Office 365 Group Id
and associates it with their Workplace Search user:
curl -X POST http://localhost:3002/api/ws/v1/sources/[CONTENT_SOURCE_KEY]/external_identities \ -H "Authorization: Bearer [ACCESS_TOKEN]" \ -H "Content-Type: application/json" \ -d '{ "user": "firstname.lastname", "source_user_id": "string" }'
{ "source_user_id": "string", "user": "firstname.lastname" }
Please note that SharePoint Online is nuanced and has a limitation.
SharePoint Online has the concept of a "Members" group that SharePoint Online manages itself. The API endpoints for the "Visitors" and "Owners" groups within their grouping system cannot be accessed via API. Therefore, if you are trying to grant access using those groups, it will not work — Workplace Search cannot understand them. We recommend creating the equivalent groups in Office 365 Groups and use that to map instead.
Custom sources
editcustom sources allow you to ingest document access information using the _allow_permissions
and _deny_permissions
fields. For more information, refer to Custom API sources guide.
Further reading:
The following sections have moved:
Organizational Sources and Private Sources → Organizational Sources and Private Sources
Which strategy should I choose? → Which strategy should I choose?
Enabling private sources → Enabling private content sources
Enabling Private Sources for Remote Content Sources → Enabling private sources for remote content sources
Enabling Private Sources for Standard Content Sources → Enabling private sources for standard content sources