Ensure that authentication enforces search hub values

This is for:

In this article

Example
Verify whether the search hub is enforced in the authentication method

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.

In Coveo for Commerce scenarios, queries target the Commerce API, which automatically enforces search hub values in queries based on the commerce interface from which the query originates.

Therefore, when creating an API key or search token for authenticating requests from a Coveo-powered Commerce solution, ensure that the API key doesn’t specify the search hub, as it’s automatically set by the Commerce API. If your index contains sensitive content that shouldn’t be visible to everyone, we recommend using source-level permissions to secure your content instead of enforcing the search hub value in the API key.

See Authenticate commerce requests for more information.

Example

Your Coveo-powered solution includes the following search interfaces:

search interface description search hub

search interface description	search hub
A customer-facing community search page	`ACMECommunitySearch`
An internal support agent Insight Panel	`ACMEAgentInsightPanel`

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 authenticated 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

query pipeline name	Condition	Filter expression
Community search	`when $searchHub is ACMECommunitySearch`	`NOT @source==("salesforce-knowledge")`
Insight Panel	`when $searchHub is ACMEAgentInsightPanel`

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.

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:

In the Coveo Administration Console, access the Query Pipelines (platform-ca | platform-eu | platform-au) page.
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.

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

In your browser, open your developer tools, and then select the Network tab.
Access the search interface that you want to test.
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.
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.
In the request headers, search for the Authorization header.
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.
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:

On the API Keys (platform-ca | platform-eu | platform-au) page, click the desired API key, and then click Edit in the Action bar.
On the subpage that opens, select the Privileges tab, and then, in the menu on the left, click Search.
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.

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 Create an API key for instructions.

While it’s usually recommended to enforce the search hub value in the API key to protect the security of content that shouldn’t be visible to everyone, this isn’t required for Coveo for Commerce solutions, since products are typically accessible to all visitors.

This can be done by setting the parameter to an empty string: Search hub is "".

Empty string in Commerce API key | Coveo

See Authenticate commerce requests for details.

If your index contains sensitive content that shouldn’t be visible to everyone, we recommend using source-level permissions to secure your content instead of enforcing the search hub value in the API key.