How it Works

The Coveo SSO solution uses browser redirections similar to what the Windows Identity Foundation (WIF) does to authenticate users with Claims-aware web applications:

• A user accesses the Coveo .NET search interface with a browser.

• When the Coveo SharePoint Claims cookie is not available or expired, the Coveo search interface web app redirects the browser to a Coveo deployed specific web page on the SharePoint server.

• This SharePoint web page uses NTLM or Kerberos so it can retrieve the full Claims identities of the user or otherwise prompts the user to login to SharePoint.

• The SharePoint web page encrypts, packages, and sends the Claims back to the Coveo search interface web app.

• The Coveo search interface web app receives the user Claims package, creates the cookie, and reloads the Coveo search interface page.

• The user now has the full Claims identities to perform his queries.

• The round trip may or may not be noticeable depending on your environment.

SharePoint Server Configuration

1. Ensure that your environment meets the following requirements:

   • SharePoint 2013/2010 (on-premises)

   • SharePoint server web application configured in Windows Claims (NTLM or Kerberos)

   • Coveo .NET Front-End 12.0.614+ (February 2014)

2. Using an administrator account, connect to the operating system of your SharePoint front-end server.

3. If not already done, deploy the Coveo integration in your SharePoint web application to ensure that at least the SharePoint Web Service option is installed (see Installing the Coveo Web Service, Search Box, and Search Interface into SharePoint).

4. On the first front-end server of your SharePoint farm, create two empty files that will be filled with the private and public communication signing keys.

   Note: The private and public keys are generated by the front-end server at the first use. You can easily regenerate new keys simply by deleting the original key files and recreating these two empty files.

   On other front-end servers of your SharePoint farm, rather paste a copy of these filled files (do not copy the empty files) to ensure that all front-end servers use the same public and private key files.

   Example: The files could be:

   • C:\Program Files\Coveo .NET Front-End 12\Web\ClaimsAuthenticationKeys\ClaimsAuthenticationPublicKey.bin

   • C:\Program Files\Coveo .NET Front-End 12\Web\ClaimsAuthenticationKeys\ClaimsAuthenticationPrivateKey.bin

   Important: Protect your private key file once it is created. This file should never be shared nor sent via email. Anyone that can access this key could use it to create his own Claims and be able to gain access to all SharePoint documents from CES.

5. Right-click the key file folder and then use its Properties to ensure that the application pool identity running the web application where Coveo is integrated has read and write access to the key files.

6. Using a text editor: 

   1. Open the web.config file of the SharePoint web application site.

      Example: The file is typically: 

      C:\inetpub\wwwroot\wss\VirtualDirectories\12345\web.config

   2. Under coveoEnterpriseSearch, if not already present, add a claimsAuthentication section, ensure it includes the following attributes, and then update the attributes values according to your setup: 

      • identityReceiverUrl="https://YourCoveoFrontEnd/ClaimsIdentityReceiver.aspx"

      • identityProviderPrivateKeyPath="PathToPrivateKey"

      • identityProviderPublicKeyPath="PathToPublicKey"

      Example: The claimsAuthentication section looks like: 

      <claimsAuthentication identityReceiverUrl="https://YourCoveoFrontEnd/ClaimsIdentityReceiver.aspx" identityProviderPrivateKeyPath="C:\Program Files\Coveo .NET Front-End 12\Web\ClaimsAuthenticationKeys\ClaimsAuthenticationPrivateKey.bin" identityProviderPublicKeyPath="C:\Program Files\Coveo .NET Front-End 12\Web\ClaimsAuthenticationKeys\ClaimsAuthenticationPublicKey.bin" />  

   3. Coveo .NET Front-End 12.0.1459+ (March 2016) When the search page is accessed via a Network Load Balancing (NLB) IP address, just before </coveoEnterpriseSearch>, you may have to add the assumedHttpRequestUrlScheme option in the following format:

      <options assumedHttpRequestUriScheme="value" />

      replacing value by either http or https.

      Important: If missing, you must add the following element before the closing sectionGroup tag (</sectionGroup>) for the assumedHttpRequestUrlScheme option to be supported:

      <section name="options" type="System.Configuration.SingleTagSectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />

      Notes:

      • When the option is present, the .NET UI assumes that the search page is always opened using the specified scheme. Otherwise, the .NET UI assumes IIS detects the right scheme.

      • You may also have to add the option in the Coveo .NET Front-End web.config file (see Coveo .NET Front-End Server Configuration).

      • You can use this option when troubleshooting the Coveo.CES.Web.Search.Security.ClaimsIdentityException: Attempt to retrieve a token in HTTP without supplying the main identity. error.

      Example: Your IIS site is configured to switch automatically in HTTPS if a browser tries to open the search page in HTTP, so you add (<options assumedHttpRequestUriScheme="https" />).

   4. If more than one standalone Coveo Front-End server use this SharePoint web application as their identity provider or if the standalone Coveo front-end server can be reached from multiple URLs, in the <identityReceivers> subsection, configure each one to allow them to retrieve the cookie.

      Example:

      <claimsAuthentication identityReceiverUrl="https://DefaultCoveoFrontEnd/ClaimsIdentityReceiver.aspx" identityProviderPrivateKeyPath="PathToPrivateKey" identityProviderPublicKeyPath="PathToPublicKey">
        <identityReceivers>
          <add domain="CoveoFrontEnd1" url="https://CoveoFrontEnd1/ClaimsIdentityReceiver.aspx" />
          <add domain="CoveoFrontEnd1DifferentUrl" url="https://CoveoFrontEnd1DifferentUrl/ClaimsIdentityReceiver.aspx" />
          <add domain="CoveoFrontEnd2" url="https://CoveoFrontEnd2/ClaimsIdentityReceiver.aspx" />
        </identityReceivers>
      </claimsAuthentication>  

      Notes:

      • Coveo .NET Front-End 12.0.777+ (May 2014) The <identityProviders> subsection is supported.

      • You should also leave a working identity receiver URL in the <claimsAuthentication> section that will be used when the user comes from another domain.

   5. Save the file.

7. Using a browser, access to the URL of the following form to test your setup:

   https://YourSharePointSite/_layouts/CES/ClaimsIdentityProvider.aspx?debug=1

   You should see a web page that contains various claims information. You should not see errors. The private and public key files should now be filled with the new key data.

8. At this point, if you want, you can remove the write access of the web application pool identity to the key files path.

Coveo .NET Front-End Server Configuration

1. Using an administrator account, connect to the operating system of your Coveo .NET Front-End server.

2. Copy the public key file created on your SharePoint front-end server and paste it to the Coveo Front-End server.

   Example: On the Coveo .NET Front-End server, you can copy the file to: 

   C:\Program Files\Coveo .NET Front-End 12\Web\ClaimsAuthenticationKeys\ClaimsAuthenticationPublicKey.bin

   Note: The public key file does not have to be secured like the private key file. It can safely be shared on a file share or sent by email.

3. Using a text editor: 

   1. Open the Coveo .NET Front-End web.config file.

      Example: The file is typically: 

      C:\Program Files\Coveo .NET Front-End 12\Web\Web.config

   2. Under coveoEnterpriseSearch, if not already present, add a claimsAuthentication section, and ensure it includes the following attributes, and then update the attributes values according to your setup: 

      • identityProviderUrl="https://YourSharePointSite/_layouts/CES/ClaimsIdentityProvider.aspx"

      • identityValidatorPublicKeyPath="PathToPublicKey"

      Example: The claimsAuthentication section looks like: 

      <claimsAuthentication identityProviderUrl="https://YourSharePointSite/_layouts/CES/ClaimsIdentityProvider.aspx" identityValidatorPublicKeyPath="C:\Program Files\Coveo .NET Front-End 12\Web\ClaimsAuthenticationKeys\ClaimsAuthenticationPublicKey.bin" />  

   3. Coveo .NET Front-End 12.0.1459+ (March 2016) When you add the assumedHttpRequestUrlScheme option in the web.config file of the SharePoint web application site, just before </coveoEnterpriseSearch>, specified the same option and value.

      Example: Your IIS site is configured to switch automatically in HTTPS if a browser tries to open the search page in HTTP, so you add (<options assumedHttpRequestUriScheme="https" />).

   4. If not already present, as shown in the following file sample, add the Coveo.CES.Web.Search.Security namespace.

      <configuration>
        <system.web>
          <pages>
            <namespaces>
              ...
              <add namespace="Coveo.CES.Web.Search.Security" />
              ...
            </namespaces>
          </pages>
        </system.web>
      </configuration>  

      Note: CES 7.0.6339– (January 2014) You need at least two CES upgrades subsequent to the CES 7.0.6424 (February 2014 monthly release) or a fresh install of the Coveo .NET Front-End to see the Coveo.CES.Web.Search.Security namespace.

   5. Save the file.

4. Using a browser, access your Coveo .NET search interface using the real hostname of the server, not localhost.

   Example: The Coveo .NET search interface page URL is typically:

   https://YourCoveoFrontEndServer/

   The first time you access the .NET search interface with a given browser, a security cookie is created (see How it Works).

   Note: When your SharePoint server is configured to prompt the users for a password, the user will have to enter its SharePoint password in the process.

5. Perform the first-time setup to configure the Coveo .NET Front-End (see Coveo .NET Front-End First Time Setup).

6. In the Coveo .NET search interface, verify that you have access to all your secured SharePoint documents. When the scope of the .NET search interface includes non-SharePoint content, also verify that you have access to this content.