---
title: Security identity cache and provider
slug: '1527'
canonical_url: https://docs.coveo.com/en/1527/
collection: index-content
source_format: adoc
---
# Security identity cache and provider
Two additional modules must intervene in the indexing and querying processes to support item [permissions](https://docs.coveo.com/en/223/) consisting of [groups](https://docs.coveo.com/en/202/) or [granted security identities](https://docs.coveo.com/en/201/): the [security identity cache](https://docs.coveo.com/en/241/) and a [security identity provider](https://docs.coveo.com/en/242/).
These modules work together to recreate and handle [security identity relationships](https://docs.coveo.com/en/1618/) and fully support [more complex secured search](https://docs.coveo.com/en/1863/) scenarios.

![Diagram showing Coveo security identity cache and provider interaction with search interface](https://docs.coveo.com/en/assets/images/index-content/permissions-interactions-index-security-cache.png)

> **Note**
>
> In this module interaction diagram:
> 
> * Blue boxes represent modules involved in the indexing process.
> However, the security identity provider is also involved in the querying process when a new [user](https://docs.coveo.com/en/250/) makes their first query (see [Identity refresh](#Identity)).
> 
> * Gray boxes represent modules involved in the querying process.
> 
> * Orange boxes represent modules involved in both the indexing and the querying process.

> **Note**
>
> To place the focus on item permission management, all examples in this article assume that the query made by the search page user matches the title of the desired items.

## [[Security2]]Security identity cache

The [basic secured search](https://docs.coveo.com/en/1749/) scenario consists of determining whether a user is allowed to access an item.
If the user's security identity is allowed to access the item, the item is returned in the user's search results.
If the user's security identity is denied access to the item or if it's not specified in the item permissions, the user can't access the item.
See [Unspecified security identities](https://docs.coveo.com/en/1749#unspecified-security-identities) for details.

In the [basic secured search scenario](https://docs.coveo.com/en/1749/), users query Coveo using a single security identity.
However, this scenario doesn't reflect the typical [permission model](https://docs.coveo.com/en/225/): administrators of secured enterprise systems often mark a group security identity as allowed to access an item instead of listing several user security identities in the item permissions.
See [Group and granted security identities](https://docs.coveo.com/en/1603/) for more information.
To support permission models including group and granted security identities, Coveo must take the relationship between the user and their group, granted identity, or [alias](https://docs.coveo.com/en/176/) into account.
See [Security identity relationships](https://docs.coveo.com/en/1618/) for details.

The security identity cache is a module that stores and maintains a list of all relationships between security identities.
Upon its first encounter with a security identity, the security identity cache queries the security identity provider to retrieve the security identity relationships.
Then, when a user logs in to a Coveo-powered search interface, the security identity cache provides them with additional security identities corresponding to their aliases, to their granted identities, and to the groups of which they're a member.
The user therefore makes a query using several security identities, which may or may not match the security identities allowed to access the queried item.

> **Note**
>
> It's not necessary to have all allowed security identities to access an item.
> An item is returned in the search results as long as:
> 
> * At least one of the user's security identities is marked as allowed to access the item.
> 
> * None of the user's security identities is marked as denied access to the item.
> 
> [[ExampleSecuredSearchWithGroups]]For example, the `R&D_Roadmap_2017.pdf` item has the following permissions:
> 
> * `board_of_directors@mycompany.com`: `allowed`
> 
> * `rd_department@mycompany.com`: `allowed`
> 
> * `interns@mycompany.com`: `denied`
> 
> John Smith wants to access `R&D_Roadmap_2017.pdf`.
> He logs in as `jsmith@mycompany.com`, and is granted the following additional security identities:
> 
> * `rd_department@mycompany.com`
> 
> * `team_leaders@mycompany.com`
> 
> * `engineers@mycompany.com`
> 
> John Smith now makes a query using the four security identities listed above.
> One of them matches the security identities allowed to access `R&D_Roadmap_2017.pdf`, and none of them is denied access to the item.
> `R&D_Roadmap_2017.pdf` is therefore returned in John Smith's search results.
> 
> ![Coveo search interface user queries as multiple security identities](:https://docs.coveo.com/en/assets/images/index-content/permissions-user-querying-as-multiple-identities.png)

## [[Security4]]Security identity provider

The role of a security identity provider is to extract all relationships of a security identity: the group members, the granted identities and the identity aliases.
See [Security identity relationships](https://docs.coveo.com/en/1618/) and [Security identity cache](#security-identity-cache) for details.
Once extracted, these relationships are stored by the Coveo security identity cache.
Therefore, the security identity provider acts as a bridge between the secured enterprise system and the Coveo security identity cache.
You can review a list of your security identity providers in the Coveo Administration Console.
See [Manage security identities](https://docs.coveo.com/en/1905/) for more information.

> **Tip**
>
> Group the security identity provider and the other implementation [resources](https://docs.coveo.com/en/2820/) together in a [project](https://docs.coveo.com/en/n7ed6189/).
> See [Manage projects](https://docs.coveo.com/en/n7ef0517/).

## [[Identity]]Identity refresh

When a newly created user logs in to a Coveo-powered search page for the first time and makes a query, this user's granted security identities are retrieved during the querying process.
The user can then access the items these [granted identities](https://docs.coveo.com/en/1603/) are allowed to access.
However, group members are only retrieved and provided to the security identity cache when the group is refreshed, that is, updated.
See [Manage security identities](https://docs.coveo.com/en/1905/) for details.

Automatic security identity refreshes are scheduled daily by default.
See [Configure security identity provider refresh schedules](https://docs.coveo.com/en/1905#configure-security-identity-refresh-schedules) for details.
These scheduled refreshes update all security identities of a security identity provider.
However, a Coveo administrator can manually refresh the identities at any time.
Such an update makes new users' group security identities available immediately rather than following the next scheduled refresh.
The administrator can either refresh the identities of all identity providers or of a single identity provider.
See [Refresh a security identity provider](https://docs.coveo.com/en/1905#refresh-a-security-identity-provider) for details.
The result is the same, that is, the security cache is updated with the new identity relationships, but updating a single security identity provider is less time- and resource-consuming.

**Example**

John Smith is a new employee at MyCompany.
The system administrator adds John Smith's user security identity, `jsmith`, to the following SomeApp groups:

* SomeApp\engineers

* SomeApp\team_leaders

The secured enterprise system also grants `SomeApp\jsmith` the following granted security identities:

* SomeApp\Everyone

* SomeApp\AllRegisteredUsers

If the Coveo administrator doesn't manually launch a security identity refresh, until the next scheduled refresh, John Smith won't be able to access `Engineers_Training.pdf`, which has the following permission model:

* SomeApp\engineers: allowed

* SomeApp\administration: allowed

* SomeApp\training_team: allowed

However, item `MyCompany_Presentation.pdf` has the following permission model:

* `SomeApp\Everyone: allowed`

John Smith can always access this item upon a first query because the granted security identities that match the item permissions have already been provided to the security identity cache.

> **Important**
>
> [[NoteItemsPermissionAndSecurityCache]]Item permissions and the security identity relationships stored in the security identity cache are updated differently.
> When [item permissions change](https://docs.coveo.com/en/1749#Permissions) (for example, you share a Google Document with someone else), this change becomes effective following an incremental refresh, a rescan, or a rebuild of the corresponding source.
> However, if members of a group change (for example, a new employee is hired and added to existing groups), the source security identities must be refreshed.

## What's next?

In a [typical secured search](https://docs.coveo.com/en/1863/) scenario, a user can access an item if at least one of their security identities is allowed to access it, and if none of their security identities is denied access to this item.