IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Permissions & Access Control Defining Document Permissions for custom sources »

› ›

Managing Document Access & Permissions for Content Sources

edit

Managing Document Access & Permissions for Content Sources

edit

The 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

edit

Document 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": "[email protected]",
	"user": "john.doe"
}

The above example would link Google’s notion of [email protected] 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

edit

Applies to Google Drive.

Google attributes an id to each user.

The id is a string, a person’s email: [email protected]

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": "[email protected]"
}'

{
  "user": "personal.person",
  "source_user_id": "[email protected]"
}

Document-level permissions for Microsoft

edit

Applies 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

edit

custom 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.