Ensure That Authentication Enforces Search Hub Values

Tune Relevance Coveo Relevance Cloud Developer System Administrator Product Documentation

In this article

Verify Whether the Search Hub Is Enforced in the Authentication Method

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

You will want to use this authentication method when your search page end users are authenticated and some (or all) of the items in your index have item-specific permissions. In this scenario, each end 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 end-users that can access the ACMECommunitySearch search interface.

By enforcing the search hub value in the authentication (search token or API key), you ensure that all queries originating 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 cannot guarantee that such content will always be displayed only to the intended end 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 Administration Console, access the Query Pipelines (platform-ca | platform-eu | platform-au) page.
In the table, every query pipeline (except the Default one) should have a searchHub-based condition (e.g., 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 (e.g., 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 authentication (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 you want to test.
Trigger a search request from the search interface. If the search interface has an input that can provide query suggestions (e.g., 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 (e.g., 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 the 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, click 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 Add an API Key for instructions.