Claims authentication

This is for:

Developer

When querying items indexed from a SharePoint server relying on claims authentication, it’s necessary to obtain certain special information from the SharePoint server to allow the end users to see the items they’re allowed to (see The Claims-Based Identity Model). There’s no way for the Coveo index to obtain this information directly from SharePoint; it can only be resolved when the querying user is logged into SharePoint. This means that the web browser must perform a round-trip to SharePoint and back before it’s possible to query the content.

The Coveo Search API provides a simple process to automate those steps. The only external requirement is that before performing queries, the end user must be redirected to a special URL. The Coveo JavaScript Search Framework provides a component that fulfills this purpose (see the AuthenticationProvider component).

Configuring claims authentication

Configuring claims authentication involves creating a SharePoint authentication with the Coveo Search API and configuring the SharePoint server properly.

Creating a SharePoint authentication with the Search API

To create a SharePoint authentication, send a POST request to https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/sharepoint, where you replace {organizationid} with the actual identifier of the target Coveo organization.

A sample SharePoint authentication creation POST request:

POST https://platform.cloud.coveo.com/rest/organizations/mycoveocloudv2organizationg8tp8wu3/authentication/sharepoint HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "name" : "mySharePointServer1",
  "uri" : "https://myserver.com/_layouts/CES/SearchAPIClaims.aspx",
  "provider" : "yourClaimsProvider",
  "secret" : "k7dbdcu3HMTtdcRtZzx4uLvKB&T9kG8O12cQ2vOcaWiNmerw3RLQLpcCAnPL8wN",
  "expiration" : 86400000
}

Parameters:

  • name (string): The name of the SharePoint server.

  • uri (string): The full URI of the page that serves the claims information.

  • provider (string): The name of the SharePoint claims security identity provider which was specifically configured for the target SharePoint Server source.

  • secret (string): The string to use to sign claims information (using HMACSHA1). This should be a random string. The longer the string, the more secure.

  • expiration (integer): How much time (in milliseconds) it takes for the browser cookie that stores the claims information to expire. If you set this parameter to 0, the cookie expires at the end of a browser session.

The body of a successful response contains the id of the SharePoint authentication.

201 Created

{
  "id" : "b5g86444-739i-4945-u9z0-0u0hp37n674b"
}

You can create many SharePoint authentications if necessary (i.e., if there are several SharePoint Server sources in the target Coveo organization).

Configuring sharepoint

The page that can compute claims information is part of the Coveo SharePoint Integration. You must install this package on your SharePoint server before proceeding (see Installing the Coveo Web Service, Search Box, and Search Interface into SharePoint).

In the web.config file of your SharePoint site, locate or create the appSettings element and add the following configuration value:

<appSettings>
  <add key="CoveoClaimsSecret" value="k7dbdcu3HMTtdcRtZzx4uLvKB&T9kG8O12cQ2vOcaWiNmerw3RLQLpcCAnPL8wN"/>
</appSettings>

The value should be the same as the secret value of your SharePoint authentication (see Creating a SharePoint Authentication with the Search API).

Recent versions of SharePoint can contain several appSettings tags in the web.config file. Be sure to add the key inside the appSettings tag that’s the direct child of the main XML element in the file.

Testing your setup

Once you’ve created your Search API SharePoint authentication and configured your SharePoint Server, you can test your setup by directing your web browser to https://platform.cloud.coveo.com/rest/search/login/{name}?organizationId={organizationId}, where you must replace {name} with the name of your SharePoint authentication (see Creating a SharePoint Authentication with the Search API), and {organizationId} with the actual identifier of the target Coveo organization.

Testing the setup:

https://platform.cloud.coveo.com/rest/search/login/mySharePointServer1?organizationId=mycoveocloudv2organizationg8tp8wu3

If everything is setup properly, the Coveo Search API should return a statusCode 200 containing a success message, along with the claims information that was obtained.

The {name} value corresponds to the value you passed as the name argument when you created your SharePoint authentication using the Coveo Search API. This value is case sensitive. If you misspell your authentication provider name in your GET request, you might get a response such as:

{
  "statusCode" : 500,
  "message" : "Invalid authentication provider: mysharepointserver1",
  "type" : "InvalidAuthenticationProviderException",
  "executionReport" : [
    {}
  ]
}

Configuring your Coveo JavaScript search page

If you’re using the Coveo JavaScript Search Framework, you should add an AuthenticationProvider component in the root element of your search interface for each available SharePoint server. The data-name attribute of an AuthenticationProvider component must match precisely the name value of an existing SharePoint authentication created using the Coveo Search API (see Creating a SharePoint Authentication with the Search API).

Configuring three distinct SharePoint authentication providers:

<!-- ... -->

<body id='search' class='CoveoSearchInterface'>

  <!-- ... -->

  <div class="CoveoAuthenticationProvider" data-name="mySharePointServer1"></div>
  <div class="CoveoAuthenticationProvider" data-name="mySharePointServer2"></div>
  <div class="CoveoAuthenticationProvider" data-name="mySharePointServer3"></div>

  <!-- ... -->

</body>

When a Coveo JavaScript Search Framework search page initially loads, it refreshes once per AuthenticationProvider component present in the root element of the search interface. It finishes loading normally unless the end user closes the web browser in the meantime.

If the end user closes and reopens the web browser, the search page refreshes again. This is because the claims information is stored in a browser cookie. By default, this cookie expires at the end of a browser session.

If you want the page to load without having to refresh again for each authentication provider, you should pass a value such as 86400000 (which is equivalent to 24 hours) as the expiration value when creating your SharePoint claims provider using the Coveo Search API. This makes the cookie expire after a set amount of time rather than at the end of a browser session.

This ensures that end users can authenticate with their SharePoint identity. This identity is sent along the query, allowing the index to return SharePoint results that the end user has access to in SharePoint.

If your search page contains a Tab component with a data-expression attribute (such as the default SharePoint.html file), make sure the value of this attribute is set properly.

Setting The data-expression attribute for a SharePoint Tab:

<div class="CoveoTab" data-id="SharePoint" data-caption="SharePoint" data-expression="@sysconnectortype==SharePoint"></div>

  • Use data-expression="@connectortype==SharePoint" to show in this only search results indexed with the latest SharePoint connector when the user selects this Tab (see Microsoft SharePoint Connector).

  • Use data-expression="@connectortype==SharePointCrawler" to show only search results indexed with the deprecated SharePoint legacy connector when the user selects this Tab (see Microsoft SharePoint Legacy Connector).

Step-by-step SharePoint claims authentication process

Here is a typical usage scenario involving SharePoint claims authentication.

  1. The end user navigates to the search page

    Since the search page is configured to log in to the SharePoint authentication provider, the browser is redirected to the login page implemented by the Coveo Search API (e.g., https://platform.cloud.coveo.com/rest/search/login/mySharePointServer1?organizationId=mycoveocloudv2organizationg8tp8wu3).

  2. The Coveo Search API redirects the end user to SharePoint

    When a request comes in the login page, the Coveo Search API looks for an existing valid authentication cookie for this provider. If it finds one, the browser is redirected back to the calling page, and queries can then be performed. Otherwise, the browser is redirected again to the page inside SharePoint that computes the claims information (e.g., http://http://hostname.com/_layouts/CES/SearchApiClaims.aspx).

  3. Claims are computed and sent back to the Coveo Search API

    When the browser tries to load a SharePoint page, the server first authenticates the user, and then loads the page. Before computing the claims information, the page validates a special signature passed through the query string to ensure that the calling page is legitimate. Then, using the login information provided by SharePoint, the needed claims information is generated, signed, and sent back to the Coveo Search API using an auto-submitting browser form.

  4. The Coveo Search API receives claims information and issues a cookie

    When the Search API receives the claims information from SharePoint, it first validates the signature to ensure it’s genuine, and then issues a signed authentication cookie containing the claims information. The cookie also includes login information from the primary authentication provider, to prevent signed claims from being used by another user. The primary authentication provider used depends on your setup. For example, if you’re using Windows authentication, the Windows login user will be used.

  5. REST queries are performed by JavaScript code in the browser

    Afterward, whenever a REST query is performed by JavaScript code, the browser automatically includes the authentication cookie along with the request. If the request specifies that the SharePoint authentication should be used (through the authentication query string parameter), the content of the cookie is sent to the index and the appropriate SharePoint items are made visible to the end user.