Managing document access & permissions for content sources
editManaging document access & permissions for content sources
editThis feature is not available for all Elastic subscription levels. Refer to the subscriptions pages for Elastic Cloud and Elastic Stack. To change your subscription level or start a trial, see Subscriptions and features.
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.
If a new user is added to Workplace Search without mapping to the corresponding external_user_id
in the third-party
service using the External Identities API reference, they will not be able to search for or see
any documents with document-level permissions.
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 Atlassian Cloud: Jira Cloud & Confluence Cloud
- Document-level permissions for Box: Box
- Document-level permissions for Dropbox: Dropbox
- Document-level permissions for GitHub: GitHub & GitHub Enterprise Server
- Document-level permissions for Google: Google Drive
- Document-level permissions for Microsoft: SharePoint Online & OneDrive
- Document-level permissions for ServiceNow: ServiceNow (partial support)
ServiceNow sources in Workplace Search only partially support ServiceNow permissions. Workplace Search supports ServiceNow base system roles, ACL rule roles, and domain separation. Workplace Search does not support ServiceNow advanced (scripted) permissions, neither does it support user criteria. Also, while ServiceNow is able to set permissions on field level, Workplace Search only supports table-wide permissions, so the ones that go deeper than the table level will not be imported.
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_user_id
and link it to its associated Workplace Search _elasticsearch_username
:
{ "external_user_id": "john.doe@example.com", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "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 Atlassian Cloud
editApplies to: Confluence Cloud, Jira Cloud
Use the external identities API to map Atlassian Cloud user IDs to Workplace Search usernames for each of your Confluence and Jira content sources.
First, gather the following information:
- Atlassian Cloud user IDs
-
The string IDs of the Atlassian Cloud users that you’d like to map to Workplace Search usernames. Example:
5b10ac8d82e05b22cc7d4ef5
.Atlassian assigns a string ID to each of its Atlassian Cloud users. The string identifies the user across all Atlassian Cloud products. However, each product has its own procedure to get the IDs:
Product Procedure to get user IDs Confluence
Within the Confluence UI, choose Settings > User Management. From the Users screen, choose Export Users. Within the data file, locate the
id
for each user.If you are using multiple Atlassian Cloud products, filter your list of IDs to only those users who can access Confluence under your Atlassian license agreement. These users have the Use Confluence permission. See Manage global permissions in the Atlassian documentation.
Jira
Use the Users resource of the Jira Cloud API to request one or more users. Within each response, locate the
accountId
for each user. - Workplace Search usernames
-
The string usernames of the Workplace Search users to which you will map Atlassian Cloud user IDs. Example:
sam_foo
.Use the appropriate UI or API to locate this information within your Elastic deployment. The specific interface depends on how you manage users.
- User mappings
-
A collection of mappings, where each maps an Atlassian Cloud user ID to a Workplace Search username.
Store this data in a format that makes sense to you. You will need to construct one or more API requests for each user mapping.
- Content source IDs and bearer token
-
The string IDs of the Confluence or Jira content sources within your Workplace Search deployment, and a bearer token, which grants access to write external identities through the API.
Then, send one API request per user mapping, per content source ID:
Request template:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/<CONTENT_SOURCE_ID>/external_identities' \ --header 'Authorization: Bearer <TOKEN>' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "<ATLASSIAN_CLOUD_USER_ID>", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "<WORKPLACE_SEARCH_USERNAME>" } ], "permissions": [] }'
Example requests:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/40bd9d00713a5d9874444410/external_identities' \ --header 'Authorization: Bearer 64c51eee12c1f7a3be8ab0ecf9a2184106c1641e49736119414da0c0e85f3611' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "91e7f8ba23a0637de213ae6d", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "john_doe" } ], "permissions": [] }'
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/8fda765d3e474d44e40369d6/external_identities' \ --header 'Authorization: Bearer 7ea05c8bd50ab5c75d2b71adbcb9ae71c4034d7a4f8d6c16a8940510a951cec7' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "5b10ac8d82e05b22cc7d4ef5", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "sam.foo" } ], "permissions": [] }'
Jira Cloud notes:
-
To ensure permissions map from Jira to Workplace Search, define project permissions directly on Jira Cloud groups (or users).
- Workplace Search does not sync other types of permission data, such as issue-level security permissions.
-
Workplace Search syncs permission data from classic Jira projects only.
- Workplace Search does not support syncing permissions from Jira next-gen projects.
-
To make a Jira project visible to all Workplace Search users, use the Any logged in user permission under Application Access.
- Workplace Search does not sync the Public group permission.
Confluence Cloud notes:
If anonymous access is enabled for a Confluence Space that you are syncing to Workplace Search, ensure anonymous access is enabled in your Confluence global permissions as well. See Manage global permissions in the Atlassian documentation.
The space with anonymous access will be searchable by all of your Workplace Search users, even those without an external identity mapping.
Document-level permissions for Box
editApplies to: Box
Use the external identities API to map Box user IDs to Workplace Search usernames for your Box organization content source.
First, gather the following information:
- Box user IDs
-
The string IDs of the Box users that you’d like to map to Workplace Search usernames. Example:
14436967113
.Use the List enterprise users endpoint of the Box API to request a list of all Box users. Within each of the
entries
, locate theid
. - Workplace Search usernames
-
The string usernames of the Workplace Search users to which you will map Box user IDs. Example:
sam_foo
.Use the appropriate UI or API to locate this information within your Elastic deployment. The specific interface depends on how you manage users.
- User mappings
-
A collection of mappings, where each maps a Box user ID to a Workplace Search username.
Store this data in a format that makes sense to you. You will need to construct one or more API requests for each user mapping.
- Content source IDs and bearer token
-
The string IDs of the Box organization content sources within your Workplace Search deployment, and a bearer token, which grants access to write external identities through the API.
Then, send one API request per user mapping, per content source ID:
Request template:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/<CONTENT_SOURCE_ID>/external_identities' \ --header 'Authorization: Bearer <TOKEN>' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "<BOX_USER_ID>", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "<WORKPLACE_SEARCH_USERNAME>" } ], "permissions": [] }'
Example requests:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/40bd9d00713a5d9874444410/external_identities' \ --header 'Authorization: Bearer 64c51eee12c1f7a3be8ab0ecf9a2184106c1641e49736119414da0c0e85f3611' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "14436967113", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "john_doe" } ], "permissions": [] }'
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/8fda765d3e474d44e40369d6/external_identities' \ --header 'Authorization: Bearer 7ea05c8bd50ab5c75d2b71adbcb9ae71c4034d7a4f8d6c16a8940510a951cec7' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "36658789235", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "sam.foo" } ], "permissions": [] }'
Document-level permissions for Dropbox
editApplies to: Dropbox
Use the external identities API to map Dropbox user IDs to Workplace Search usernames for your Dropbox organization content source.
A Dropbox Business plan is required in order to enable document-level permissions.
First, gather the following information:
- Dropbox user IDs
-
The string IDs of the Dropbox users that you’d like to map to Workplace Search usernames. Dropbox user IDs are email addresses. Example:
sam.foo@example.com
.You can export a list of users from the Dropbox Business Admin Console.
- Workplace Search usernames
-
The string usernames of the Workplace Search users to which you will map Dropbox user IDs. Example:
sam_foo
.Use the appropriate UI or API to locate this information within your Elastic deployment. The specific interface depends on how you manage users.
- User mappings
-
A collection of mappings, where each maps a Dropbox user ID to a Workplace Search username.
Store this data in a format that makes sense to you. You will need to construct one or more API requests for each user mapping.
- Content source IDs and bearer token
-
The string IDs of the Dropbox organization content sources within your Workplace Search deployment, and a bearer token, which grants access to write external identities through the API.
Then, send one API request per user mapping, per content source ID:
Request template:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/<CONTENT_SOURCE_ID>/external_identities' \ --header 'Authorization: Bearer <TOKEN>' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "<DROPBOX_USER_EMAIL>", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "<WORKPLACE_SEARCH_USERNAME>" } ], "permissions": [] }'
Example requests:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/40bd9d00713a5d9874444410/external_identities' \ --header 'Authorization: Bearer 64c51eee12c1f7a3be8ab0ecf9a2184106c1641e49736119414da0c0e85f3611' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "john.doe@example.com", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "john_doe" } ], "permissions": [] }'
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/8fda765d3e474d44e40369d6/external_identities' \ --header 'Authorization: Bearer 7ea05c8bd50ab5c75d2b71adbcb9ae71c4034d7a4f8d6c16a8940510a951cec7' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "sam.foo@example.com", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "sam.foo" } ], "permissions": [] }'
Document-level permissions for GitHub
editApplies to: GitHub, GitHub Enterprise Server
Use the external identities API to map GitHub usernames to Workplace Search usernames for your GitHub and GitHub Enterprise Server organization content source.
A GitHub organization admin-level user is required to connect the content source to enable document-level permissions.
First, gather the following information:
- GitHub usernames
-
The usernames of the GitHub users that you’d like to map to Workplace Search usernames. GitHub usernames are the unique string to identify the user. Example:
sam-foo
.You can export members of an organization. Within the GitHub UI, go to the organzation, click People > Export as csv. Within the data file, locate the
login
for each user. - Workplace Search usernames
-
The string usernames of the Workplace Search users to which you will map GitHub usernames. Example:
sam_foo
.Use the appropriate UI or API to locate this information within your Elastic deployment. The specific interface depends on how you manage users.
- User mappings
-
A collection of mappings, where each maps a GitHub username to a Workplace Search username.
Store this data in a format that makes sense to you. You will need to construct one or more API requests for each user mapping.
- Content source IDs and bearer token
-
The string IDs of the Dropbox organization content sources within your Workplace Search deployment, and a bearer token, which grants you access to write external identities through the API.
Then, send one API request per user mapping, per content source ID:
Request template:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/<CONTENT_SOURCE_ID>/external_identities' \ --header 'Authorization: Bearer <TOKEN>' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "<GITHUB_USERNAME>", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "<WORKPLACE_SEARCH_USERNAME>" } ], "permissions": [] }'
Example requests:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/40bd9d00713a5d9874444410/external_identities' \ --header 'Authorization: Bearer 64c51eee12c1f7a3be8ab0ecf9a2184106c1641e49736119414da0c0e85f3611' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "john-doe", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "john_doe" } ], "permissions": [] }'
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/8fda765d3e474d44e40369d6/external_identities' \ --header 'Authorization: Bearer 7ea05c8bd50ab5c75d2b71adbcb9ae71c4034d7a4f8d6c16a8940510a951cec7' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "sam-foo", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "sam.foo" } ], "permissions": [] }'
GitHub Enterprise Server notes:
Internal repositories will be treated the same as private repositories.
Document-level permissions for Google
editApplies to: Google Drive
Use the external identities API to map Google user IDs to Workplace Search usernames for your Google Drive organization content source.
First, gather the following information:
- Google user IDs
-
The string IDs of the Google users that you’d like to map to Workplace Search usernames. Google user IDs are email addresses. Example:
sam.foo@example.com
.See View or export a group’s members in the Google documentation for instructions to export all users.
- Workplace Search usernames
-
The string usernames of the Workplace Search users to which you will map Google user IDs. Example:
sam_foo
.Use the appropriate UI or API to locate this information within your Elastic deployment. The specific interface depends on how you manage users.
- User mappings
-
A collection of mappings, where each maps a Google user ID to a Workplace Search username.
Store this data in a format that makes sense to you. You will need to construct one or more API requests for each user mapping.
- Content source IDs and bearer token
-
The string IDs of the Google Drive organization content sources within your Workplace Search deployment, and a bearer token, which grants access to write external identities through the API.
Then, send one API request per user mapping, per content source ID:
Request template:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/<CONTENT_SOURCE_ID>/external_identities' \ --header 'Authorization: Bearer <TOKEN>' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "<GOOGLE_USER_ID>", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "<WORKPLACE_SEARCH_USERNAME>" } ], "permissions": [] }'
Example requests:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/40bd9d00713a5d9874444410/external_identities' \ --header 'Authorization: Bearer 64c51eee12c1f7a3be8ab0ecf9a2184106c1641e49736119414da0c0e85f3611' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "john.doe@example.com", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "john_doe" } ], "permissions": [] }'
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/8fda765d3e474d44e40369d6/external_identities' \ --header 'Authorization: Bearer 7ea05c8bd50ab5c75d2b71adbcb9ae71c4034d7a4f8d6c16a8940510a951cec7' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "sam.foo@example.com", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "sam.foo" } ], "permissions": [] }'
Document-level permissions for Microsoft
editApplies to: OneDrive, SharePoint Online
Use the external identities API to map user IDs from Microsoft Office 365 Groups to usernames from Workplace Search for your OneDrive and SharePoint Online organization content source.
First, gather the following information:
- Microsoft Office 365 Groups user IDs
-
The string IDs of the Microsoft Office 365 Groups users that you’d like to map to Workplace Search usernames. Each ID is an opaque string. Example:
32ad7bda-3de1-4a77-ee97-f3476c2cf58d
.To export user IDs, log in to your Microsoft Admin, then navigate to Users. Select the users you would like to export, and click Export Users.
- Workplace Search usernames
-
The string usernames of the Workplace Search users to which you will map Microsoft user IDs. Example:
sam_foo
.Use the appropriate UI or API to locate this information within your Elastic deployment. The specific interface depends on how you manage users.
- User mappings
-
A collection of mappings, where each maps a Microsoft user ID to a Workplace Search username.
Store this data in a format that makes sense to you. You will need to construct one or more API requests for each user mapping.
- Content source IDs and bearer token
-
The string IDs of the OneDrive or SharePoint Online organization content sources within your Workplace Search deployment, and a bearer token, which grants access to write external identities through the API.
Then, send one API request per user mapping, per content source ID:
Request template:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/<CONTENT_SOURCE_ID>/external_identities' \ --header 'Authorization: Bearer <TOKEN>' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "<MICROSOFT_USER_ID>", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "<WORKPLACE_SEARCH_USERNAME>" } ], "permissions": [] }'
Example requests:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/40bd9d00713a5d9874444410/external_identities' \ --header 'Authorization: Bearer 64c51eee12c1f7a3be8ab0ecf9a2184106c1641e49736119414da0c0e85f3611' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "32ad7bda-3de1-4a77-ee97-f3476c2cf58d", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "john_doe" } ], "permissions": [] }'
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/8fda765d3e474d44e40369d6/external_identities' \ --header 'Authorization: Bearer 7ea05c8bd50ab5c75d2b71adbcb9ae71c4034d7a4f8d6c16a8940510a951cec7' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "64bc9acd-5df2-5a88-ff98-a4496c2c568e", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "sam.foo" } ], "permissions": [] }'
SharePoint Online notes:
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.
Document-level permissions for ServiceNow
editApplies to: ServiceNow
Use the external identities API to map user emails from ServiceNow to usernames from Workplace Search for your ServiceNow organization content source.
First, gather the following information:
- ServiceNow user IDs
-
The emails of ServiceNow users that you’d like to map to Workplace Search usernames. Each ServiceNow user can see it on his own account page. Example:
sam.foo@example.com
. - Workplace Search usernames
-
The string usernames of the Workplace Search users to which you will map ServiceNow user emails. Example:
sam.foo
.Use the appropriate UI or API to locate this information within your Elastic deployment. The specific interface depends on how you manage users.
- User mappings
-
A collection of mappings, where each maps a ServiceNow user email to a Workplace Search username.
Store this data in a format that makes sense to you. You will need to construct one or more API requests for each user mapping.
- Content source IDs and bearer token
-
The string IDs of the Confluence or Jira content sources within your Workplace Search deployment, and a bearer token, which grants access to write external identities through the API.
Then, send one API request per user mapping, per content source ID:
Request template:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/<CONTENT_SOURCE_ID>/external_identities' \ --header 'Authorization: Bearer <TOKEN>' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "<SERVICENOW_USER_EMAIL>", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "<WORKPLACE_SEARCH_USERNAME>" } ], "permissions": [] }'
Example request:
curl \ --request 'POST' \ --url '<ENTERPRISE_SEARCH_BASE_URL>/api/ws/v1/sources/8fda765d3e474d44e40369d6/external_identities' \ --header 'Authorization: Bearer 7ea05c8bd50ab5c75d2b71adbcb9ae71c4034d7a4f8d6c16a8940510a951cec7' \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "sam.foo@example.com", "external_user_properties": [ { "attribute_name": "_elasticsearch_username", "attribute_value": "sam.foo" } ], "permissions": [] }'
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.
Content source ID and bearer token
editEach call to the external identities API must include the ID of the Workplace Search content source. Each call must also include a bearer token or other credential to grant access. Each of these values is an opaque string, as in the following examples:
-
Content source ID:
8fda765d3e474d44e40369d6
. -
Bearer token:
7ea05c8bd50ab5c75d2b71adbcb9ae71c4034d7a4f8d6c16a8940510a951cec7
.
Locate the content source ID:
- Within Kibana, navigate to Search → Enterprise Search → Workplace Search → Sources.
- Locate the desired content source, and choose Details.
-
Within your web browser, locate the current URL. The URL has the following structure:
<kibana_base_url>/app/enterprise_search/workplace_search/sources/<content_source_id>
-
Extract the content source ID from the final segment of the URL. For example, given this URL path:
/app/enterprise_search/workplace_search/sources/61d4c1dd231c0487548ad806
The content source ID is
61d4c1dd231c0487548ad806
.
Locate a bearer token or other credential for access:
Choose one of the following credential types:
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