---
title: Defining source-level permissions
slug: '3246'
canonical_url: https://docs.coveo.com/en/3246/
collection: index-content
source_format: adoc
---
# Defining source-level permissions
Most [connectors](https://docs.coveo.com/en/2734/) support the [**Same users and groups as in your content system**](https://docs.coveo.com/en/1779#same-users-and-groups-as-in-your-content-system) content security option, which sets [permissions](https://docs.coveo.com/en/223/) at the [item](https://docs.coveo.com/en/210/) level.
This means that Coveo has permission information detailing who is allowed or denied access to each individual item through a Coveo-powered [search interface](https://docs.coveo.com/en/2741/).

However, [some connectors](https://docs.coveo.com/en/1702#connector-types) don't support indexing the original permission system and replicating it in a search interface.
An alternative way to secure your [source](https://docs.coveo.com/en/246/) content is to define permissions manually, at the source level.
In other words, you can specify who can access the items [indexed](https://docs.coveo.com/en/204/) with this source.
This solution applies to the source as a whole, so end users are allowed to access either all source items or none.

There are two ways to define source-level permissions:

* Through the [**Specific users and groups**](https://docs.coveo.com/en/1779#specific-users-and-groups) content security option in your source's configuration panel (recommended whenever possible).

* Through a modification of the source's JSON configuration.

This page explains how to proceed with the latter.
You should only do so when using the **Specific users and groups** option is impossible or incompatible with your use case.
For example, the **Specific users and groups** option only allows selecting users or groups from the Email Security Provider.
To select identities from another security provider, such as Salesforce identities, you must modify your source JSON configuration.

First, create a source whose content is accessible to you only.
Then, [edit the source JSON configuration](https://docs.coveo.com/en/1685/) to specify who else should be allowed to access its content through a Coveo-powered search interface.
You can expand the access restriction to other [user](https://docs.coveo.com/en/250/) or [group](https://docs.coveo.com/en/202/) [security identities](https://docs.coveo.com/en/240/).

For more information on how Coveo handles permissions, see [Coveo management of security identities and item permissions](https://docs.coveo.com/en/1719/).

To configure source-level permissions

. [Create a source with the desired connector](https://docs.coveo.com/en/1702/).
On the **Content Security** tab of the source creation panel, select **Specific users and groups**.
Once you're done, click **Save**.
. In the [source JSON configuration](https://docs.coveo.com/en/1685/), specifically the `Permissions` object, define the source permissions.
See the [Reference](#reference) section for details on each object.
. [Build your source](https://docs.coveo.com/en/3390#refresh-rescan-or-rebuild-sources).

## Example

You want only two specific employees to be able to access your SharePoint source content.
The corresponding SharePoint security provider works with claims, so you provide this information under `additionalInfo`.

In the `permissionSets` object of the source JSON configuration, you modify the `allowedPermissions` to allow only the desired users.

```json
"permissions": [
  {
    "name": "Source-Level Permissions",
    "permissionSets": [
      {
        "name": "Two Employees",
        "allowedPermissions": [
          {
            "identity": "i:0#.f|membership|user1@ORGID.com",
            "identityType": "User",
            "securityProvider": "SHAREPOINT_ONLINE2-PROVIDERID-ORGID",
            "additionalInfo": {
              "claims": "c:0t.c|tenant|58fg0183-6121-038a-a00d-lopp6ef4b22q"
            }
          },
          {
            "identity": "i:0#.f|membership|user2@domain.ORGID.com",
            "identityType": "User",
            "securityProvider": "SHAREPOINT_ONLINE2-PROVIDERID-ORGID",
            "additionalInfo": {
              "claims": "c:0t.c|tenant|m29384yc-723b-g23m-0la7-8grgsw3dg07p"
            }
          }
        ],
        "deniedPermissions": []
      }
    ]
  }
]
```

## Reference

### Permissions (array of [Permission Set object](#permission-set-object))

The `Permissions` array contains the permission sets to apply to the items indexed in your source.
The security identities listed in these levels and sets are either allowed or denied access to the indexed items.

See the [Permission Set Object](#permission-set-object) section for details on the properties in this object.

### Permission Set object

A Permission Set object describes a single permission set, which contains lists of allowed and denied security identities.

For more information on how Coveo handles permissions, see [Coveo management of security identities and item permissions](https://docs.coveo.com/en/1719/).

#### Name (String)

The name of the permission set.

#### AllowedPermissions (array of [Permission object](#permission-object))

Each object in the `AllowedPermissions` array represents a security identity that should be allowed to access the indexed content.

> **Note**
>
> If a user is listed under both `AllowedPermissions` and [`DeniedPermissions`](#deniedpermissions-array-of-permission-object), the [denial prevails](https://docs.coveo.com/en/1618#denial-prevalence) so that security holes are avoided.
> 
> For more information on how Coveo handles permissions, see [Coveo management of security identities and item permissions](https://docs.coveo.com/en/1719/).

See the [Permission Object](#permission-object) section for details on the properties expected in the `AllowedPermissions` object.

#### DeniedPermissions (array of [Permission object](#permission-object))

Each object in the `DeniedPermissions` array represents a security identity to whom access to the indexed item should be denied.

> **Note**
>
> If a user is both listed under [`AllowedPermissions`](#allowedpermissions-array-of-permission-object) and `DeniedPermissions`, the [denial prevails](https://docs.coveo.com/en/1618#denial-prevalence) so that security holes are avoided.
> 
> For more information on how Coveo handles permissions, see [Coveo management of security identities and item permissions](https://docs.coveo.com/en/1719/).

See the [Permission Object](#permission-object) section for details on the properties expected in the `DeniedPermissions` object.

### Permission object

A `Permission` object describes a security identity that can be either allowed or denied in a source [permission set](#permission-set-object).

See [`AllowedPermissions`](#allowedpermissions-array-of-permission-object) and [`DeniedPermissions`](#deniedpermissions-array-of-permission-object) for more details.

#### Identity (string, required)

The name of the security identity.
By default, the Email Security Provider is used and therefore email addresses are expected, but you can specify a different [`SecurityProvider`](#securityprovider-string-required) to use.

#### IdentityType (string enum, required)

The type of security identity.
Allowed values are `User`, `Group`, `VirtualGroup`.

For more information on these types of security identities, see [Coveo management of security identities and item permissions](https://docs.coveo.com/en/1719/).

#### SecurityProvider (string, required)

The unique identifier of the target [security identity provider](https://docs.coveo.com/en/242/) that manages the specified [identity](#identity-string-required), as displayed on the [**Security Identities**](https://platform.cloud.coveo.com/admin/#/orgid/content/permissions/providers/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/permissions/providers/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/permissions/providers/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/permissions/providers/)) Administration Console page.
By default, the Email Security Provider is used.

#### AdditionalInfo (array of [AdditionalInfo object](#additionalinfo-object))

`AdditionalInfo` can be used to enrich a [security identity](https://docs.coveo.com/en/240/) with custom information to make it unique.
For example, if two users have the same name, `AdditionalInfo` lets you specify more information about each user, like their employee ID.
This custom information is part of the security identity, just like its name and its type.

Each key in the `AdditionalInfo` object represents the name of a piece of metadata, while the corresponding value is the value path (simple path or JSONPath) in your API's JSON response.

### AdditionalInfo object

Any additional information required by the [security provider](#securityprovider-string-required).
This can be attributes, claims, URLs, etc.