Authenticate via search token

This is for:

Developer

In this article

Prerequisites
Back-end configuration
Front-end configuration

This article explains how to employ Coveo search token authentication in an SAP Commerce Cloud project. Using this authentication method provides better security, as it doesn’t require exposing the API key in the front-end code.

Prerequisites

Make sure your configuration meets the following criteria:

The Apache Ant utility is installed on your machine.
You added an Omni Commerce Connect (OCC) extension to your project.
You have a Coveo-powered search UI embedded in your SAP Commerce Cloud storefront. See Use Coveo Search in SAP Commerce Cloud Composable Storefront.

Back-end configuration

Step 1: Add an OCC extension

To use search token authentication, you must add a new API to the OCC extension of your project. Whereas you can do so by building a new extension from scratch, we recommend using the prebuilt extension published on Coveo GitHub: https://github.com/coveo/coveocc

Go to your SAP project folder.
Navigate to the hybris/bin/custom folder.
Clone or download the extension repository. This would create a new folder named coveocc.
In the project folder, open the hybris/config/localextensions.xml file and add the coveocc extension:
```
<extension name='coveocc' />
```
Save the file.

Step 2: Build and run the server

From the root of your project folder, run the following command:
```
ant clean all
```
After the command execution, navigate to the hybris/bin/platform folder.
Run the hybrisserver.sh script:
```
./hybrisserver.sh
```

Step 3: Specify credentials

The Coveo credentials should be set through the graphical interface of the Backoffice Administration Cockpit.

In the Administration Cockpit, go to the WCMS → Website page.
In the list of websites, double-click the required website.
Switch to the Administration tab.
Fill in the following fields:
- Coveo Platform URL. For production, it must be https://platform.cloud.coveo.com/.
- Coveo API Key. The API key must have the Impersonate privilege granted. See Impersonate domain.

Local testing

To test retrieving a search token, you can use a Swagger UI that’s available when you’re running the hybrisserver.sh script. By default, the Swagger UI is available at https://localhost:9002/occ/v2/swagger-ui.html, where you can find and test the getSearchToken endpoint.

Note

By default, your local server would use ports 9001 (http) and 9002 (https).

Front-end configuration

Step 1: Add a new file

Navigate to the root of your angular application (e.g., src/app folder).

Create a new file, access-token.ts:

import { environment } from "../environments/environment";

interface GetAccessTokenOptions {
  searchHub: string;
  refresh?: boolean;
}

export async function getAccessToken(options: GetAccessTokenOptions) { 
  const { searchHub, refresh = false } = options;

  const cache = createTokenCache(searchHub)
  const cachedToken = cache.get();

  if (cachedToken && !refresh) return cachedToken;

  const token = await generateAccessToken(searchHub);
  token && cache.set(token);

  return token;
}

async function generateAccessToken(searchHub: string) { 
  const url = getCoveoAccessTokenUrl(searchHub);

  try {
    const res = await fetch(url);
    const data = await res.json();
    return data.token;
  } catch (e) {
    return '';
  }
}

function getCoveoAccessTokenUrl(searchHub: string) {
  const base = environment.occBaseUrl;
  const baseSiteId = '<YOUR_SITE_ID>'; 
  return `${base}occ/v2/${baseSiteId}/coveo/token/${searchHub}`
}

function createTokenCache(searchHub: string) { 
  const key = `coveo-${searchHub}` 
  const get = () => localStorage.getItem(key)
  const set = (token: string) => localStorage.setItem(key, token)
  return { get, set }
}

	`getAccessToken` checks if there’s a token in the localStorage. If not, it calls `generateAccessToken` to create and retrieve a new token.
	`generateAccessToken` calls the `getCoveoAccessTokenUrl` function which returns the URL of OCC extension that retrieves the token.
	Saves the ID of your site into a `baseSiteId` variable. The site ID is the one that you configured in the Backoffice Administration Cockpit.
	`createTokenCache` creates a cache object that exposes `get` and `set` methods to retrieve and store the token in the localStorage.
	A separate cache entry is created if the `searchHub` value wasn’t in the localStorage.

Step 2: Update `app.component.ts`

Update the src/app/app.component.ts file to use the getAccessToken method:

import { getAccessToken } from './access-token';

export class AppComponent implements AfterViewInit {
  async ngAfterViewInit() {
    const searchInterface = document.querySelector('atomic-search-interface');

    const searchHub = `<YOUR_SEARCH_HUB>`;
    const accessToken = await getAccessToken({searchHub});

    if (!accessToken) {
      return;
    }

    searchInterface
      ?.initialize({
        organizationId: '<YOUR_ORG_ID>', 
        search: { searchHub },
        accessToken,
        renewAccessToken: () => getAccessToken({ searchHub, refresh: true })
      })
      .then(() => {
        const engine = searchInterface.engine;
        if (engine) {

          // ... 

          searchInterface.executeFirstSearch();
        }
      });
  }
}

	Pass the following parameters: ID of your Coveo organization Search hub Access token `renewAccessToken` method that renews the token if it’s expired. When `refresh` is set to `true`, the method ignores the cached tokens. See initialize.
	You can further specify the engine configuration before executing the first search. See atomic-search-interface properties.