THIS IS ARCHIVED DOCUMENTATION

Using Windows Authentication to Query External Sources

This is for:

Developer System Administrator

On-Premises only

Coveo for Sitecore allows you to integrate external content directly in search results returned by a Coveo-Powered Search Page. Often, security isn’t much of a concern, as Sitecore and external content items are both visible publicly. However, external content - such as an intranet website - can also be secured. This content may be secured with Windows permissions, for example. This page explains how to deal with this type of mixed permission (Sitecore and Windows) in Coveo for Sitecore.

Understanding Mixed Authentication

Being able to search for external content items in a Coveo-Powered Search Page means that it’s able to deal with “mixed authentication.” In other words, the user is performing a query using several identities at the same time. The diagram below illustrates how the Coveo Search API service deals with mixed authentication (that is, Sitecore and Windows).

  1. The browser calls the REST endpoint to get search results.
  2. The REST endpoint forwards the call to the Search API, giving it the known Sitecore user identity and asking the Search API to perform Windows authentication.
  3. The Search API performs Windows authentication with the client browser. The Windows user identity is now known by the Search API and can be added to the search request.
  4. The Search API sends the search query to the search index (CES) for processing.
  5. CES computes the results considering permissions for both the Sitecore user identity and the Windows user identity. Search results are then returned to the Search API, REST endpoint, and finally to the client browser.
    1. Search results are returned to the Search API.
    2. Search results are returned to the REST endpoint.
    3. Search results are returned to the client browser.

Considerations

Since the REST endpoint delegates the authentication process to the Search API, there are some rules that need to be respected. Otherwise, the authentication mechanism won’t work, and the Windows user identity won’t be added to the search query.

  • The Search API service must be installed on the same server as the Sitecore instance.
  • The host name used to connect to the Search API service must be the same as the one used by the client browser to connect to the Sitecore instance.
  • The host name must correspond to the machine name. Adding a fake host name in the hosts file doesn’t work.

Note that CES can safely be installed on a different server since the Search API and CES are using certificates to trust each other.

Configuring for Mixed Authentication

In this section, it’s assumed that:

  • The external source already exists in CES.
  • The Search API service is installed on the same server as the Sitecore instance.
  • The appropriate ports are opened in the firewall.

Step 1: Configure the REST Endpoint to Use the Correct Hostname

As mentioned above, the host name used to connect to the Sitecore instance must be the same as the one used by the REST endpoint to connect to the Search API.

  1. Edit the Coveo.SearchProvider.Rest.Custom.config file. The file is located in the C:\inetpub\wwwroot\yourSitecoreInstance\Website\App_Config\Include\Coveo folder.
  2. Find the searchApiUri element.

  3. Adjust the value to use the correct host name. In this article, the machine name is wks-000362. Since the Search API is configured to run on port 8080 by default, we should configure the element like this:

     <searchApiUri>http://wks-000362:8080/</searchApiUri>
  4. Save the file.

Step 2: Add the External Source to the Search Page

  1. Open the search page in the Page Editor.
  2. Edit the properties of the Coveo Search component.

  3. Because some rules are defined by default, you may need to add a new condition to the Filtering Rules field (Enterprise only), to include the results from the external source.

    1. Select the where specific field compares to specific value condition.
    2. It will appear inside the Basic filtering rule as and where specific field compares to specific value.
    3. Click the and link to turn it into an or.
    4. Click the specific link and enter syssource.
    5. Click the compares to link and select equals to.
    6. Click the specific value and enter the external source name. In this case, it’s Shared Files.

    7. The Basic filtering rule will now look like this.

    8. Click OK to close the rule editor.
  4. Find the External Content section and enter the name of the external source you want to add in the Names of External Content Sources field. If you want to add all sources from a collection, you can select the appropriate collection from the Names of External Content Collections list.
  5. Save changes and, optionally, publish changes.

Step 3: Asking the Search API to Perform Windows Authentication

Coveo for Sitecore 4.1 (November 2018)

You now need to tell the Search API that, in this search page, you want to perform Windows authentication in addition to the user identity that’s provided (the Sitecore user identity in this case). This might sound complicated, but the JavaScript Search Framework V1.0 provides a nice component to do that. It’s the Authentication Provider component.

  1. Duplicate the sublayout (or view) file that corresponds to your search component. The defaults are:
    1. CoveoSearch.ascx for Web Forms. It’s located in C:\inetpub\wwwroot\yourSitecoreInstance\Website\layouts\Coveo.
    2. SearchView.cshtml for MVC. It’s located in C:\inetpub\wwwroot\yourSitecoreInstance\Website\Views\Coveo.

  2. In your copy, find the element with a class attribute equal to CoveoSearchInterface:

     <div id="search" class="CoveoSearchInterface" ...

  3. Right after the opening element, add the Authentication Provider component.

     <div class="CoveoAuthenticationProvider" data-name="Windows"></div>
  4. Save the file.

Testing It Out

For this example, we have two different users wks-000362\john and wks-000362\mary. The external source contains one file that both users can access and one file that’s private to each user. When accessing the search page, each user can see the right items.

So, when John visits the search page, he gets this result.

As you can see, John sees the Sitecore items. These come from the Sitecore source. He also sees John's Private Document and Shared Document that come from the external source. As expected, he can’t see Mary’s private document.

The same thing happens for Mary when she visits the same search page.