---
title: Security identity definition examples
slug: '42'
canonical_url: https://docs.coveo.com/en/42/
collection: index-content
source_format: adoc
---
# Security identity definition examples
The [permission model](https://docs.coveo.com/en/225/) of a secured [item](https://docs.coveo.com/en/210/) typically refers to existing [security identities](https://docs.coveo.com/en/240/), which the Push API allows you to define and manage in a [security identity provider](https://docs.coveo.com/en/242/).

A security identity definition must minimally contain the name of the defined security identity itself, as well as its entity type (that is, `User`, `Group`, `VirtualGroup`, or `Unknown`).
Additionally, it may contain:

* The name and entity type of each of its [members](https://docs.coveo.com/en/2873/), if the defined security identity is a [group](https://docs.coveo.com/en/202/) or [virtual group](https://docs.coveo.com/en/252/).
* The name and entity type (normally, `Group` or `VirtualGroup`) of each of its [granted identities](https://docs.coveo.com/en/201/).

> **Note**
>
> _Granted identities_ used to be called _well known groups._
> 
> For backwards compatibility reasons, the Push API still requires you to specify the granted identities of a security identity in an array property whose name is `wellKnowns`.

See [`IdentityBody` model](https://docs.coveo.com/en/78#identitybody-model) for details.

The following security identity definition examples rely on one another and are increasingly complex.

## Defining a basic group

A [group](https://docs.coveo.com/en/202/) typically has an array of `Members`, unless this group is intended to be used as a [granted identity](#defining-a-granted-identity).

```json
{
  "identity": {
    "name": "SampleTeam1",
    "type": "Group"
  },
  "members": [
    {
      "name": "asmith@example.com",
      "type": "User"
    },
    {
      "name": "bjones@example.com",
      "type": "User"
    }
  ]
}
```

In this example, the `asmith@example.com` and `bjones@example.com` users are explicitly included as members of the `SampleTeam1` group.

You would typically create aliases on those members to map them to their respective corresponding identities in other security identity providers.
See [About the Email Security Provider](https://docs.coveo.com/en/87/) and [User alias definition examples](https://docs.coveo.com/en/46/) for details on this process.

> **Important**
>
> When pushing a [group](https://docs.coveo.com/en/202/), you overwrite the current version of that group.
> Therefore, to keep existing group members, be sure to include them in the new group configuration.
> If this isn't viable, consider using [granted security identities](https://docs.coveo.com/en/1603#granted-security-identities) instead.

## Defining a granted identity

A [granted identity](https://docs.coveo.com/en/201/) is initially defined as a [group](https://docs.coveo.com/en/202/) or [virtual group](https://docs.coveo.com/en/252/) that doesn't have an array of `Members`.

```json
{
  "identity": {
    "name": "Everyone",
    "type": "Group"
  }
}
```

> **Note**
>
> While uncommon, it's possible for a granted identity to have its own array of `wellKnowns`.

In this example, the `Everyone` group doesn't have any members.
Actually, those members will be included "the other way around".
For more information, see [Defining a user with granted identities](#defining-a-user-with-granted-identities).

## Defining a user with granted identities

A [granted identity](https://docs.coveo.com/en/201/) is essentially a [group](https://docs.coveo.com/en/202/) whose members are included "the other way around".

Whenever you define a [security identity](https://docs.coveo.com/en/240/), it automatically becomes a member of all granted identities included in its array of `wellKnowns`.

In the following example, suppose that the `Domain Users` group was previously defined exactly as the `Everyone` group was.
For more information, see [Defining a granted identity](#defining-a-granted-identity).

```json
{
  "identity": {
    "name": "cbrown@example.com",
    "type": "User"
  },
  "wellKnowns": [
    {
      "name": "Domain Users",
      "type": "Group"
    },
    {
      "name": "Everyone",
      "type": "Group"
    }
  ]
}
```

In this example, the `cbrown@example.com` [user](https://docs.coveo.com/en/250/) automatically becomes a member of the `Domain Users` and `Everyone` groups.

> **Note**
>
> A [user](https://docs.coveo.com/en/250/) entity can also be defined with one or several [aliases](https://docs.coveo.com/en/176/).
> For more information, see [User alias definition examples](https://docs.coveo.com/en/46/).

## Example cases of when to use granted identities

It's not always necessary to use granted identities in Coveo implementations.
They should be considered when they can serve as a simplifying measure.
Below are some example cases.

* A group named `Everyone` is attributed to all users by default.
This group is meant to denote membership to a given organization.
Every time a new member joins the organization, they must be added to the group, and inversely when a member leaves.
This requires a lot of group management and can quickly lead to human errors.
To prevent this scenario, the granted identity `Everyone` can be systematically used when declaring new users:

```json
{
  "identity": {
    "name": "newuser@example.com",
    "type": "User"
  },
  "wellKnowns": [
    {
      "name": "Everyone",
      "type": "Group"
    }
  ]
}
```

* In a case where group membership eligibility can be determined based on a set of automated rules, it can be wise to link users to groups on user creation.
Conversely, if the rule was applied on group creation, the system would need to iterate over every existing member to determine which ones qualify for group membership, for every group.
A better design is to run the group membership rules on user creation and to use granted identities:

```json
{
  "identity": {
    "name": "newuser@example.com",
    "type": "User"
  },
  "wellKnowns": [
    {
      "name": "Everyone",
      "type": "Group"
    },
    {
      "name": "Security_Team",
      "type": "Group"
    },
    {
      "name": "Developer",
      "type": "Group"
    },
    ...
  ]
}
```

## Defining a group with many member types

A [group](https://docs.coveo.com/en/202/) can have many security identity types in its array of Members.

```json
{
  "identity": {
    "name": "SampleTeam2",
    "type": "Group"
  },
  "members": [
    {
      "name": "Domain Users",
      "type": "Group"
    },
    {
      "name": "dmoore@example.com",
      "type": "User"
    }
  ]
}
```

In this example, since the `Domain Users` group is included as a member of the `SampleTeam2` group, all users who have the `Domain Users` [granted identity](#defining-a-user-with-granted-identities) also become members of the `SampleTeam2` group.

Consequently, the `cbrown@example.com` user becomes a member of the `SampleTeam2` group.

You would typically create an alias on `dmoore@example.com` to map that identity to corresponding identities in other security identity providers.
See [About the Email Security Provider](https://docs.coveo.com/en/87/) and [User alias definition examples](https://docs.coveo.com/en/46/) for details on this process.

> **Important**
>
> When pushing a [group](https://docs.coveo.com/en/202/), you overwrite the current version of that group.
> Therefore, to keep existing group members, be sure to include them in the new group configuration.
> If this isn't viable, consider using [granted security identities](https://docs.coveo.com/en/1603#granted-security-identities) instead.

## Defining a group with granted identities

A [group](https://docs.coveo.com/en/202/) can have [granted identities](https://docs.coveo.com/en/201/).
Any [security identity](https://docs.coveo.com/en/240/) that's a member of that group receives these granted identities.

In the following example, suppose that the `Superuser` group was previously defined exactly as the `Everyone` group was.
For more information, see [Defining a granted identity](#defining-a-granted-identity).

```json
{
  "identity": {
    "name": "SampleGroup",
    "type": "VirtualGroup"
  },
  "members": [
    {
      "name": "SampleTeam1",
      "type": "Group"
    },
    {
      "name": "SampleTeam2",
      "type": "Group"
    }
  ],
  "wellKnowns": [
    {
      "name": "Superuser",
      "type": "Group"
    }
  ]
}
```

> **Note**
>
> In this example, the `SampleGroup` security identity is defined as a [virtual group](https://docs.coveo.com/en/252/).
> 
> The only difference between a _group_ and a _virtual group_ is semantics: a virtual group doesn't exist in the indexed enterprise system, whereas a group does.

In this example, the `SampleGroup` virtual group ultimately resolves to the following individual user entities:

* `asmith@example.com` and `bjones@example.com`   Those two users are explicitly listed as members of the `SampleTeam1` group.
For more information, see [Defining a basic group](#defining-a-basic-group).
* `cbrown@example.com`   This user is defined as having the `Everyone` granted identity, and all members of the `Everyone` group are included as members of the `SampleTeam2` group.
For more information, see [Defining a user with granted identities](#defining-a-user-with-granted-identities) and [Defining a group with many member types](#defining-a-group-with-many-member-types).
* `dmoore@example.com`   This user is explicitly listed as member of the `SampleTeam2` group.
For more information, see [Defining a group with many member types](#defining-a-group-with-many-member-types).

Each of those users automatically becomes a member of the `Superuser` group.

## How security identities and permission models interact

Once all security identities in the security identity provider have been properly resolved to individual [user](https://docs.coveo.com/en/250/) entities, the index can evaluate the [effective permissions](https://docs.coveo.com/en/194/) of each item in the secured Push source.
For more information, see [Effective permission evaluation with the simplified permission model](https://docs.coveo.com/en/107#effective-permission-evaluation).

Suppose that an item in a secured Push source has the following permission model.
For more information, see [Simplified permission model](https://docs.coveo.com/en/107/).

```json
[
  {
    "allowAnonymous": false,
    "allowedPermissions": [
      {
        "identity": "Superusers",
        "identityType": "Group"
      }
    ],
    "deniedPermissions": [
      {
        "identity": "MysteryUserX",
        "identityType": "User"
      }
    ]
  }
]
```

Moreover, suppose that the `MysteryUserX` alias has been defined as follows in the same security identity provider.
For more information, see [User alias definition examples](https://docs.coveo.com/en/46/).

```json
{
  "identity": {
    "name": "MysteryUserX",
    "type": "User"
  },
  "mappings": [
    {
      "name": "asmith@example.com",
      "type": "User",
      "provider": "Email Security Provider"
    }
  ]
}
```

In this example:

* The `Superusers` group resolves to the `asmith@example.com`, `bjones@example.com`, `cbrown@example.com`, and `dmoore@example.com` users.
For more information, see [Defining a group with many member types](#defining-a-group-with-many-member-types).
* The `MysteryUserX` alias resolves to the `asmith@example.com` user entity.
* As a result, once effective permission have been evaluated, the `asmith@example.com` user is denied access to the item, and only the `bjones@example.com`, `cbrown@example.com`, and `dmoore@example.com` users can see the item in their query results.