Ensure that authentication enforces search hub values
Ensure that authentication enforces search hub values
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 |
---|---|
A customer-facing community search page |
|
An internal support agent Insight Panel |
|
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 |
---|---|---|
Community search |
|
|
Insight Panel |
|
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. |
Verify whether the search hub is enforced in the authentication method
Note
While the following procedure recommends enforcing the |
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, |
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 Add 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: 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. |