--- title: Configure claims authentication slug: '113' canonical_url: https://docs.coveo.com/en/113/ collection: build-a-search-ui source_format: adoc --- # Configure claims authentication When [querying](https://docs.coveo.com/en/231/) [items](https://docs.coveo.com/en/210/) that are [indexed](https://docs.coveo.com/en/204/) from a SharePoint server which relies on [claims](https://msdn.microsoft.com/en-ca/library/ee517291.aspx) [authentication](https://docs.coveo.com/en/2120/), 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](https://docs.coveo.com/en/lcdf0493/), you can use the [`@coveo/auth`](https://github.com/coveo/ui-kit/tree/main/packages/auth) package to configure claims authentication for the search engine component. * If you're using the [Coveo JavaScript Search Framework](https://docs.coveo.com/en/187/), you can use the [`AuthenticationProvider`](https://coveo.github.io/search-ui/components/authenticationprovider.html) component to enable claims authentication. > **Note** > > When performing [queries](https://docs.coveo.com/en/231/) 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](https://docs.coveo.com/en/lcdf0493/) package or [JavaScript Search Framework](https://docs.coveo.com/en/187/) 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](#create-a-sharepoint-authentication-with-the-search-api) with the Coveo Search API and [configure the SharePoint server](#configure-sharepoint). ## Search API login flow 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. ![Search API login flow](https://docs.coveo.com/en/assets/images/coveo-platform/search-api-redirections.svg) . The user enters a query in the search box. . The search page sends a call to the Search API at `/rest/search`. > **Important** > > If you're not using the [Headless](https://docs.coveo.com/en/lcdf0493/) `@coveo/auth` package or [JavaScript Search Framework](https://docs.coveo.com/en/187/) `AuthenticationProvider` component, you'll have to add the `authentication=` parameter to the [query](https://docs.coveo.com/en/231/). > 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 request 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: ```text 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 sends back an HTML form that automatically makes a POST request to the Search API. . The search page then sends a POST request at `/rest/search/login/handshake`. . The Search API validates the request and redirects the user to the search page with a handshake token. .. The Search API doesn't provide the search token directly, because it might be too long to fit into the URL. .. This redirection uses the URL stored in the `redirectUri` parameter. . Once the handshake is complete, the search page sends a request to the Search API at `/rest/search/login` with the user's authenticated identities to obtain the search token. . The Search API returns a response with the search token. . The authenticated user can now perform queries on the search page. > **Important** > > If you're not using the [Headless](https://docs.coveo.com/en/lcdf0493/) `@coveo/auth` package or [JavaScript Search Framework](https://docs.coveo.com/en/187/) `AuthenticationProvider` component, you'll have to add the `authentication=` parameter to the [query](https://docs.coveo.com/en/231/). > 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. ## 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. :leveloffset!: ## 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](https://docs.coveo.com/en/185/) (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** ```http POST https://platform.cloud.coveo.com/rest/organizations/mycoveoorganizationg8tp8wu3/authentication/sharepoint HTTP/1.1 ​ Content-Type: application/json Accept: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload** ```json { "name" : "mySharePointServer1", "uri" : "https://myserver.com/_layouts/CES/SearchAPIClaims.aspx", "provider" : "yourClaimsProvider", "secret" : "k7dbdcu3HMTtdcRtZzx4uLvKB&T9kG8O12cQ2vOcaWiNmerw3RLQLpcCAnPL8wN", "expiration" : 86400000, "enforceTrustedUris": true } ``` **201 Created response body** ```json { "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](https://onlinehelp.coveo.com/en/ces/7.0/administrator/installing_the_coveo_web_service_search_box_and_search_interface_into_sharepoint.htm) on your SharePoint server 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](#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](#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](https://www.coveo.com/go?dest=adminhelp70&lcid=9&context=4218) before proceeding. In the `web.config` file of your SharePoint site, locate or create the `appSettings` element and add the following configuration value: ```xml ``` The `value` should be the same as the `secret` value of [your SharePoint authentication](#create-a-sharepoint-authentication-with-the-search-api). > **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](#view-recent-untrusted-redirections) and [configure allowed redirections](#configure-allowed-redirections). > **Important** > > Untrusted redirections are allowed by default in the Search API. > For now, you must set the [`enforceTrustedUris`](#enforcetrusteduris-boolean) parameter to `true` in your SAML authentication provider to authorize redirections. > > In the future, however, the default behavior will be to prevent untrusted redirections. > 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: ```json { "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: ```json { "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** ```http POST https://platform.cloud.coveo.com/rest/organizations/mycoveoorganizationg8tp8wu3/authentication/trusteduris HTTP/1.1 ​ Content-Type: application/json Authorization: Bearer **********-****-****-****-************ ``` **Payload** ```json { "trustedUri": { "uriPrefix": "https://www.example.com" } } ``` **201 Created response body** ```json { "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. :leveloffset!: ## 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`](#name-string-required) of your [SharePoint authentication](#create-a-sharepoint-authentication-with-the-search-api). `{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: > > ```json { "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](#create-a-sharepoint-authentication-with-the-search-api) 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: ```html
``` > **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: ```xml
``` * Use `data-expression="@connectortype==SharePoint"` to show only search results that were indexed with the latest [SharePoint connector](https://www.coveo.com/go?dest=adminhelp70&lcid=9&context=4104) 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](https://www.coveo.com/go?dest=adminhelp70&lcid=9&context=16) when the user selects this Tab.