Authenticate via search token

This is for:

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 directory.
Navigate to the hybris/bin/custom directory.
Clone or download the extension repository. This would create a new directory named coveocc.
In the project directory, 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 directory, run the following command:
```
ant clean all
```
After the command execution, navigate to the hybris/bin/platform directory.
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 sites, 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, your local server would use ports 9001 (http) and 9002 (https). The Swagger UI is available at https://localhost:9002/occ/v2/swagger-ui.html, where you can find and test the /coveo/token/ endpoint.

This endpoint returns a JSON object with the token property that contains the search token. Depending on the user type, the endpoint returns a JWT token for a logged-in user or an anonymous user.

Note

Your implementation may use price groups to manage user-specific pricing. Price groups can be attached to a user group or directly to the user.

Either way, JWT tokens will contain all the price group IDs that are associated with a logged-in user.

See more about user groups in the SAP documentation.

Front-end configuration

Step 1: Add a new file

Navigate to the root of your angular application (for example, src/app directory).

Create a new service for token management, search-token-service/search-token.service.ts:

import { CoreEngine } from '@coveo/atomic-angular'
import { loadConfigurationActions } from '@coveo/headless'
import { EventEmitter, Injectable, InjectionToken, Inject } from '@angular/core';
import { AuthStorageService, EventService, LoginEvent, LogoutEvent } from '@spartacus/core';
import {environment} from "../../environments/environment";

export const SEARCH_HUB = new InjectionToken<string>('searchHub');

@Injectable()
export class SearchTokenService {
  public newTokenGenerated: EventEmitter<string> = new EventEmitter<string>();
  private TOKEN_PREFIX: string = `coveo-jwt`;
  private readonly searchHub: string

  constructor(
    private events: EventService,
    private authStorageService: AuthStorageService,
    @Inject(SEARCH_HUB) searchHub: string) {

    this.searchHub = searchHub;
    this.events
      .get(LogoutEvent)
      .subscribe( () => {
        removeAccessToken(this.TOKEN_PREFIX, this.searchHub);
        this.emitEvent();
      });

    this.events
      .get(LoginEvent)
      .subscribe(() => {
        this.emitEvent();
      });
  }

  getToken() {
    return getAccessToken({
      prefix: this.TOKEN_PREFIX,
      searchHub: this.searchHub,
      hybrisToken: this.authStorageService.getItem('access_token')})
  }

  refreshToken() {
    return getAccessToken({
      prefix: this.TOKEN_PREFIX,
      searchHub: this.searchHub,
      refresh: true,
      hybrisToken: this.authStorageService.getItem('access_token')})
  }

  reloadSearchEngineWithToken(engine: CoreEngine, token: string) { 
    if (engine) {
      const {updateBasicConfiguration} = loadConfigurationActions(engine);
      const action = updateBasicConfiguration({accessToken: token})
      engine.dispatch(action);
    }
  }

  private async emitEvent() {
    this.newTokenGenerated.emit(await getAccessToken({ 
      prefix: this.TOKEN_PREFIX,
      searchHub: this.searchHub,
      hybrisToken: this.authStorageService.getItem('access_token')
    }));
  }
}

function removeAccessToken(prefix: string, searchHub: string) {
  for (let i = 0; i < localStorage.length; i++) {
    const key = localStorage.key(i)
    if (key && key.startsWith(`${prefix}-${searchHub}`) && !key.startsWith(`${prefix}-${searchHub}-guest`)) {
      localStorage.removeItem(key)
    }
  }
}

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

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

  const usertype = hybrisToken ? 'user' : 'guest'; 
  const cache = createTokenCache(prefix, usertype, searchHub);

  const cachedToken = cache.get();

  if (cachedToken && !refresh) return cachedToken;

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

  return token;
}

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

async function generateAccessToken(searchHub: string, hybrisToken: string | undefined) { 
  const url = getCoveoAccessTokenUrl(searchHub);
  const headers: Record<string, string> = {};
  if (hybrisToken) {
    headers['Authorization'] = `Bearer ${hybrisToken}`;
  }

  const requestOptions: RequestInit = {
    method: 'GET',
    headers: headers,
  };

  try {
    const response = await fetch(url, requestOptions);
    const data = await response.json();
    return data.token;
  } catch (error) {
    console.error('Request failed:', error);
    return '';
  }
}

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

	`reloadSearchEngineWithToken` updates the engine configuration with the new JWT token when a user changes its authentication status. Once a user logs in or logs out, the `emitEvent` method is called to emit a new token.
	The service uses the `emitEvent` method to inform the app about the generation of a new token and retrieve it.
	`getAccessToken` checks if checks if there’s a token in the localStorage. If not, it check whether it’s a logged-in user or an anonymous user and creats a cache token based on the user type. Finally, it calls `generateAccessToken` to create and retrieve a new token.
	`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.
	`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.

Step 2: Update `app.component.ts`

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

import {SearchTokenService, SEARCH_HUB} from "./search-token-service/search-token.service";

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

    const searchHub = `<YOUR_SEARCH_HUB>`;
    const accessToken = await this.searchTokenService.getToken()

    if (!accessToken) {
      return;
    }

    initalizeSearchInterface(accessToken)

    this.searchTokenService.newTokenGenerated.subscribe((value) => { 
      const engine = this?.searchInterface?.engine;
      if (engine) {
        this.searchTokenService.reloadSearchEngineWithToken(engine, value)
      } else {
        this.initalizeSearchInterface(value)
      }
    });

    initalizeSearchInterface(accessToken) = {
      searchInterface
      ?.initialize({
        organizationId: '<YOUR_ORG_ID>', 
        search: { searchHub: searchHub },
        accessToken,
        renewAccessToken: () => this.searchTokenService.refreshToken()
      })
      .then(() => {
        const engine = searchInterface.engine;
        if (engine) {

          // ... 

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

	Subscribe to the `newTokenGenerated` event to reload the engine with the new JWT token.
	Pass the following parameters: ID of your Coveo organization Search hub Access token `renewAccessToken` method that renews the token if it’s expired. See initialize.
	You can further specify the engine configuration before executing the first search. See atomic-search-interface properties.