Ensure that authentication enforces search hub values

This is for:

Developer System Administrator

Any search interface that relies on the Coveo Platform regularly performs authenticated HTTP requests against the Search API and Usage Analytics Write API. The most secure query authentication method is search token authentication.

You’ll want to use this authentication method when your search page users are authenticated and some (or all) of the items in your index have item-specific permissions. In this scenario, each user gets a unique search token, allowing the search interface to return only the items that the user is allowed to see.

Both the search token and API key authentication methods allow you to enforce a search hub value, which we strongly recommend to protect the security of content that shouldn’t be visible to everyone.

Example

Your Coveo-powered solution includes the following search interfaces:

search interface description search hub

A customer-facing community search page

ACMECommunitySearch

An internal support agent Insight Panel

ACMEAgentInsightPanel

The ACMECommunitySearch search interface provides public information that everyone can access, whereas the ACMEAgentInsightPanel search interface also includes information that must only be visible to {authorized} users (support agents).

In your Coveo organization, you create a distinct query pipeline using the recommended condition-based query pipeline routing mechanism for each search interface:

query pipeline name Condition Filter expression

Community search

when $searchHub is ACMECommunitySearch

NOT @source==(“salesforce-knowledge”)

Insight Panel

when $searchHub is ACMEAgentInsightPanel

The Community Search pipeline contains a filter query pipeline rule (NOT @source==(“salesforce-knowledge”)) that filters content that shouldn’t be exposed to users that can access the ACMECommunitySearch search interface.

By enforcing the search hub value in the search token or API key, you ensure that all queries which originate from the ACMECommunitySearch search interface are routed to the proper pipeline.

Warning

We strongly advise against using query pipeline rules to prevent the exposure of filtered content as we can’t guarantee that such content will always be displayed only to the intended users.

For example, items from a source whose content is accessible to everyone ("sourceVisibility": "PUBLIC") could be exposed if a Coveo administrator, unaware of the reason behind the query pipeline rule, modifies or removes the query pipeline rule.

If you still decide to configure filter rules to filter secured content from a search interface, you should always base the filter rule on the cq query parameter.

Verify whether the search hub is enforced in the authentication method

Note

While the following procedure recommends enforcing the searchHub parameter in the search token for safer routing, you could also enforce the pipeline parameter in the search token to route queries.

To comply with the recommended query authentication method, you should verify the following:

Step 1: Verify that your queries are properly routed

You should validate that your implementation uses the recommended condition-based query pipeline routing mechanism:

  1. In the Coveo Administration Console, access the Query Pipelines (platform-ca | platform-eu | platform-au) page.

  2. In the table, every query pipeline should have a searchHub-based condition except for the Default one. For example, Search Hub is MySearchHub.

If your queries aren’t routed using this mechanism, see Condition-based routing (recommended) for instructions.

Important

You should always use positive operators (for example, is, contains, or matches) when creating a condition that aims at routing the queries originating from a specific search interface to a given query pipeline.

Step 2: Validate that the search hub is enforced in the authentication

In a Coveo-powered solution, each distinct search interface should be identified by its own unique search hub value (see Set the Search Hub).

This search hub value should be enforced in the search token or API key to ensure that queries are routed to the proper query pipeline.

The procedure varies depending on whether you’re using search token or API key authentication:

Search token authentication

  1. In your browser, open your developer tools, and then select the Network tab.

  2. Access the search interface that you want to test.

  3. Trigger a search request from the search interface. If the search interface has an input that can provide query suggestions, such as a search box, you should test both query and query suggestion requests.

  4. In your browser tools, search for a POST request made against a Coveo search endpoint. For example, you can use a filter such as cloud.coveo.com/rest/search.

  5. In the request headers, search for the Authorization header.

  6. Copy the value of the Authorization header (the token), and then use a JSON web token decoder such as JWT to decode the search token.

  7. In the decoded payload, search for the searchHub parameter.

If the searchHub parameter is in the search token, it means that this search hub is enforced through the search token. If you don’t see the searchHub parameter, we strongly recommend that you enforce the searchHub parameter in the search token. See Search token authentication for instructions.

API key authentication

If you’re using API key authentication, you can verify if a search hub value is enforced in the API key directly in the Coveo Administration Console:

  1. On the API Keys (platform-ca | platform-eu | platform-au) page, click the desired API key, and then click Edit in the Action bar.

  2. On the subpage that opens, select the Privileges tab, and then, in the menu on the left, click Search.

  3. Scroll down to the bottom of the list of privileges. If your API key has been granted privileges that warrant limiting its scope to a search hub, a section appears to let you select a search hub.

Search hub in API key | Coveo

If you see a search hub value in the Limit the API key scope section, it means that this search hub is enforced in the API key. If no value is present, we strongly recommend that you enforce a search hub in this API key if a query pipeline has this search hub as a query pipeline condition. See Add an API key for instructions.