Security identity cache and provider

This is for:

Developer System Administrator

Two additional modules must intervene in the indexing and querying processes to support item permissions consisting of groups or granted security identities: the security identity cache and a security identity provider. These modules work together to recreate and handle security identity relationships and fully support more complex secured search scenarios.

CCV2-Permissions-SecurityIdentityCacheAndProviders
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 makes their first query (see Identity refresh).

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

Security identity cache

The basic secured search 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 for details.

In the basic secured search scenario, users query Coveo using a single security identity. However, this scenario doesn’t reflect the typical permission model: 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 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 into account. See Security identity relationships 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.

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 his four security identities. 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.

CCV2-Permissions-SecurityCache

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 and 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 for more information.

Tip

Group the security identity provider and the other implementation resources together in a project. See Manage projects.

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 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 for details.

Automatic security identity refreshes are scheduled daily by default. See Configure security identity provider 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 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. On his first day of work, the system administrator adds John Smith’s user security identity, jsmith, to the following Jive groups:

  • Jive\engineers

  • Jive\team_leaders

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

  • Jive\Everyone

  • Jive\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:

  • Jive\engineers: allowed

  • Jive\administration: allowed

  • Jive\training_team: allowed

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

  • Jive\Everyone: allowed

John Smith can always access this item upon his first query because his granted security identities, among which one matches the item permissions, have already been provided to the security identity cache.

Important

Item permissions and the security identity relationships stored in the security identity cache are updated differently. When item permissions change (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 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.