Understanding How to Leverage Virtual Users With Coveo

This is for:

Developer System Administrator

In this article

Rule 1: Add Roles on the Virtual User
Rule 2: Log In With the Proper Method
Rule 3: Have the Proper Permissions Set on the Sitecore Items
How It Works

Legacy feature

This article pertains to achieving relevance with the Coveo Hive framework. Coveo Hive is now in maintenance mode.

See Achieve relevance for guidance on leveraging Coveo Platform relevance features with the Coveo Atomic library.

Virtual users are a feature of Sitecore that enables you to dynamically create non-Sitecore users and assign them Sitecore roles.

These users can only be created using the Sitecore API. According to Sitecore documentation, creating a typical virtual user looks like this:

Sitecore.Security.Accounts.User user = Sitecore.Security.Authentication.AuthenticationManager.BuildVirtualUser(@"dummy\user",true);
if (user != null) {
    string domainRole = @"sitecore\Sitecore Client Users";
    if (Sitecore.Security.Accounts.Role.Exists(domainRole)) {
        user.Roles.Add(Sitecore.Security.Accounts.Role.FromName(domainRole));
    }

    Sitecore.Security.UserProfile profile = user.Profile;
    profile.FullName = "Dummy User";
    profile.Save();
    Sitecore.Security.Authentication.AuthenticationManager.Login(user);
}

Coveo for Sitecore supports these virtual users on REST (JavaScript Search UI Framework) queries and injects it its roles.

To make sure that it works, you need to follow a few rules.

Rule 1: Add Roles on the Virtual User

The roles are used as additional identities on the queries to Coveo. This is how you’re able to resolve the permissions on items.

If there are no roles assigned to the virtual user, Coveo isn’t able to resolve this user as a Sitecore user.

Rule 2: Log In With the Proper Method

The AuthenticationManager offers various calls to log in the virtual user. In the provided example, you’re using the method that takes the user object as a parameter.

There’s also a Login method that takes only the user name as a parameter. This method won’t work; virtual users in this case aren’t considered persistent, and the Sitecore API doesn’t return them.

Rule 3: Have the Proper Permissions Set on the Sitecore Items

If all items have anonymous permission set on them in Sitecore, you don’t have to set anything.

If, for example, anonymous is denied, ensure that the items have the virtual user roles allowed on items, either explicitly or by inheritance.

If the roles aren’t allowed, Coveo denies the virtual user access to items.

How It Works

The Coveo Security Provider adds the Sitecore users to the Coveo Security Cache. At query time, the Security Provider compares the user performing the query with the user list in that cache. If the user is known and is allowed on the item, then the item is returned.

Virtual users aren’t part of the Sitecore User Manager list, which means that the Security Provider isn’t able to add it to the cache. The AddVirtualGroups processor declared in the getSearchUserIdentities pipeline resolves the virtual user back to the Role it’s assigned to.

This processor can be found in the Coveo.SearchProvider.Rest.config file.

The Index will then receive the Sitecore role, not the virtual user.