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 »
Elastic Docs › ›Permissions & Access Control

Managing document access & permissions for content sources

edit

Managing document access & permissions for content sources

edit

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

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:

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": "[email protected]",
    "external_user_properties": [
        {
            "attribute_name": "_elasticsearch_username",
            "attribute_value": "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 Atlassian Cloud

edit

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

See Content source ID and bearer token.

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

edit

Applies 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 the id.

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.

See Content source ID and bearer token.

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

edit

Applies 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: [email protected].

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.

See Content source ID and bearer token.

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": "[email protected]",
    "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": "[email protected]",
    "external_user_properties": [
        {
            "attribute_name": "_elasticsearch_username",
            "attribute_value": "sam.foo"
        }
    ],
    "permissions": []
}'

Document-level permissions for GitHub

edit

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

See Content source ID and bearer token.

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

edit

Applies 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: [email protected].

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.

See Content source ID and bearer token.

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": "[email protected]",
    "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": "[email protected]",
    "external_user_properties": [
        {
            "attribute_name": "_elasticsearch_username",
            "attribute_value": "sam.foo"
        }
    ],
    "permissions": []
}'

Document-level permissions for Microsoft

edit

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

See Content source ID and bearer token.

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

edit

Applies 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: [email protected].

servicenow user email
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.

See Content source ID and bearer token.

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": "[email protected]",
    "external_user_properties": [
        {
            "attribute_name": "_elasticsearch_username",
            "attribute_value": "sam.foo"
        }
    ],
    "permissions": []
}'

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.

Content source ID and bearer token

edit

Each 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:

  1. Within Kibana, navigate to Enterprise Search → Workplace Search → Sources.
  2. Locate the desired content source, and choose Details.

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

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

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