Configure claims authentication

This is for:

Developer

In this article

Search API login flow
Create a SharePoint authentication with the Search API
Request body properties
Configure SharePoint
Authorize redirections
Test your setup
Configure your Coveo JavaScript search page

When querying items that are indexed from a SharePoint server which relies on claims authentication, special information from the SharePoint server is needed so that users can see the items that they’re allowed to access. The Coveo index can’t obtain this information directly from SharePoint. It can only be resolved when the querying user is logged into SharePoint, so the user’s web browser must perform a round trip to SharePoint and back before they can query the content.

The Coveo Search API provides a process to automate these steps. The only external requirement is that before performing queries, the user must be redirected to a special URL.

If you’re using the Coveo Headless library, you can use the @coveo/auth package to configure claims authentication for the search engine component.
If you’re using the Coveo JavaScript Search Framework, you can use the AuthenticationProvider component to enable claims authentication.

Note

When performing queries that leverage claims authentication, you have to inform the Search API that you want to use the identities from a given provider. This is handled for you when you use the Headless package or JavaScript Search Framework component. If you’re not using either of these, however, you’ll have to add an additional authentication parameter to the query.

To configure claims authentication, you’ll have to create a SharePoint authentication with the Coveo Search API and configure the SharePoint server.

Authentication often involves one or more redirections to accumulate identities from IdPs. The following schema illustrates the flow of redirections when an unauthenticated user accesses a secured search interface.

The user enters a query in the search box.

The search page sends a call to the Search API at /rest/search.

If you’re not using the Headless @coveo/auth package or JavaScript Search Framework AuthenticationProvider component, you’ll have to add the authentication=<YOUR_AUTHENTICATION_PROVIDER_NAME> parameter to the query. It tells the Search API that you want to use the identities from the given provider. Without this parameter, the search may fail, or it might not find the right documents because it’s anonymous.

The user’s credentials are invalid, so the Search API returns an error.
The search page sends a call to the Search API at /rest/search/login to begin the login process.

This call includes the redirectUri parameter, which is typically set to the current URL of the search page:
```
https://searchdev.cloud.coveo.com/rest/search/login/mySAMLAuthenticationProvider?organizationId=mycoveoorganizationg8tp8wu3&redirectUri=https://www.example.com
```
The Search API redirects the user’s browser to the third-party authentication provider.
The user logs in to the authentication provider.
The authentication provider redirects the user’s browser back to the Search API at /rest/search/login. This call includes the user’s authenticated identities.
The Search API temporarily stores these identities and returns a handshake token to the user by redirecting to the search page.
1. The Search API doesn’t provide the search token directly, because it might be too long to fit into the URL.
2. This redirection uses the URL stored in the redirectUri parameter.
The search page sends a call to the Search API at /rest/search/login/handshake. This call includes the handshake token, and the response includes the search token.

The authenticated user can now perform queries on the search page.

Step-by-step SharePoint claims authentication process

Here is a typical usage scenario involving SharePoint claims authentication.

The 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 (for example, https://platform.cloud.coveo.com/rest/search/v2/login/mySharePointServer1?organizationId=mycoveocloudv2organizationg8tp8wu3).
The Coveo Search API redirects the user to SharePoint

When a request is sent to 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 (for example, http://hostname.com/_layouts/CES/SearchApiClaims.aspx).
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.
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.
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 user.

Create 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 unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).

You can create many SharePoint authentications if necessary, such as when there are several SharePoint Server sources in the target Coveo organization.

Example

POST https://platform.cloud.coveo.com/rest/organizations/mycoveoorganizationg8tp8wu3/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,
  "enforceTrustedUris": true
}

201 Created response body

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

Request body properties

`expiration` (unsigned integer, required)

How much time (in milliseconds) it takes for the browser cookie that stores the claims information to expire. Setting this parameter to 0 means that the cookie will expire at the end of a browser session.

Sample value: 86400000

`name` (string, required)

The name of the SharePoint claims authentication provider.

Sample value: mySharePointServer1

`provider` (string, required)

The name of the SharePoint claims security identity provider which was specifically configured for the target SharePoint Server source.

Sample value: yourClaimsProvider

`uri` (string, required)

The full URI of the page that serves the claims information for this SharePoint server.

Note

This page is part of the Coveo SharePoint integration. You must install this package on your SharePoint server if you want to implement claims authentication in a search page.

Sample value: https://myserver.com/_layouts/CES/SearchAPIClaims.aspx

`enforceTrustedUris` (Boolean)

Whether redirections to the search page are limited to a list of trusted URIs. You can authorize redirections to improve the security of your Coveo-powered search implementation.

Important

This feature is currently turned off by default to avoid breaking existing implementations. When this parameter is set to true, it prevents all redirections until you’ve configured a list of trusted URIs.

If you would like to enable this feature, we recommend that you follow the instructions in the Authorize redirections section and create a list of trusted URIs first.

Sample value: true

`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 it will be.

Sample value: k7dbdcu3HMTtdcRtZzx4uLvKB&T9kG8O12cQ2vOcaWiNmerw3RLQLpcCAnPL8wN

Configure SharePoint

Important

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.

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.

Note

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.

Authorize redirections

To ensure the security of your search implementation, every redirection to your search page should come from an authorized URL. If you’re using a SharePoint server through the Search API, you can view a list of recent untrusted redirections and configure allowed redirections.

Important

Untrusted redirections are allowed by default in the Search API. For now, you must set the enforceTrustedUris parameter to true in your SAML authentication provider to authorize redirections.

In the future, however, the default behavior will be to prevent untrusted redirections. We recommend that you configure allowed redirections now to improve the security of your implementation and ensure a smooth transition when unauthorized redirections become blocked by default.

View recent untrusted redirections

Before you authorize any redirections, you should view the list of recent untrusted redirections by sending a GET request to:

https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/trusteduris/recentuntrusted?page=0&perPage=20

where {organizationId} is the unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).

If there have been any recent untrusted redirections, you’ll receive a response similar to the following:

{
  "totalCount": 1,
  "items": [
    {
      "uriPrefix": "https://www.example.com",
      "date": "INSERT DATE"
    }
  ]
}

You can use this list to determine which redirections you want to allow.

Configure allowed redirections

To view the current list of trusted URIs, send a GET request to:

https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/trusteduris?page=0&perPage=20

where {organizationId} is the unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).

If you haven’t added any trusted URIs yet, you’ll receive an empty array. If you have, you’ll receive a response similar to the following:

{
  "totalCount": 1,
  "items": [
    {
      "id": "371af96a-18a2-11e8-accf-0ed5f89f718b",
      "uriPrefix": "https://www.example.com"
    }
  ]
}

Add a trusted URI

To add a trusted URI, send a POST request to:

https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/trusteduris

where {organizationId} is the unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).

Example

POST https://platform.cloud.coveo.com/rest/organizations/mycoveoorganizationg8tp8wu3/authentication/trusteduris HTTP/1.1

Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "trustedUri": {
    "uriPrefix": "https://www.example.com"
  }
}

201 Created response body

{
  "trustedUri": {
    "id": "371af96a-18a2-11e8-accf-0ed5f89f718b",
    "uriPrefix": "https://www.example.com"
  }
}

Remove a trusted URI

To remove a trusted URI, send a DELETE request to:

https://platform.cloud.coveo.com/rest/organizations/{organizationId}/authentication/trusteduris/{uriId}

where:

{organizationId} is the unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).
{uriId} is the unique identifier of the URI that you want to remove from the list of trusted URIs.

Test your setup

Once you’ve created your Search API SharePoint authentication, configured your SharePoint Server, and authorized redirections, you can test your setup by directing your web browser to: https://platform.cloud.coveo.com/rest/search/v2/login/{name}?organizationId={organizationId}

where:

{name} is the name of your SharePoint authentication.

{organizationId} is the unique identifier of your Coveo organization (for example, mycoveoorganizationg8tp8wu3).

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

Note

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" : [
    {}
  ]
}

Configure your Coveo JavaScript search page

If you’re using the 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 the name value of an existing SharePoint authentication created using the Coveo Search API. This ensures that users can authenticate with their SharePoint identity. This identity is sent along the query, allowing the index to return SharePoint results that the user has access to in SharePoint.

Example

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>

Note

When a 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 user closes the web browser in the meantime.

If the 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.

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

Example

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 only search results that were indexed with the latest SharePoint connector when the user selects this Tab.
Use data-expression="@connectortype==SharePointCrawler" to show only search results that were indexed with the deprecated SharePoint legacy connector when the user selects this Tab.