Integrate the Drupal Key Module with SearchStax

The Drupal Key module lets you store SearchStax credentials outside the Drupal database so sensitive values, such as API keys and access tokens, aren't exposed in configuration or source control.

Overview

The Key module stores references to secrets instead of the secrets themselves. You define where a key lives, such as a private file or environment variable, and Drupal reads the value only when it's needed. This approach improves security and reduces the risk of accidental exposure.

For SearchStax integrations, you can use the Key module to store:

• Analytics URLs
• Analytics access tokens
• App API URLs
• App API access tokens

Drupal stores only the reference to each key. The actual values live in a secure location outside the database.

Before You Start

Before you begin, you must have:

• A working Drupal site
• Access to the Drupal admin UI
• Composer and Drush installed
• A SearchStax account with access to your App and Analytics credentials
• The required Drupal modules installed and enabled:
  • Search API
  • Search API Solr
  • SearchStax

Before you create any keys, configure Drupal to use a private file directory so sensitive values can be stored securely.

Configure the Private File Directory

Note: Drupal must be configured to use a private file directory before you create or reference keys. If this setting is missing, Drupal won't be able to read key values stored in private files.

Add the following line to your settings.php file:

$settings['file_private_path'] = $app_root . '/../private';

Install Required Drupal Modules

Install the Search API Module

Install the Search API module with Composer:

composer require drupal/search_api

Enable the module using Drush:

drush en search_api -y

For more information, see the Search API module documentation.

Install the Search API Solr Module

Install the Search API Solr module with Composer:

composer require drupal/search_api_solr

Enable the module using Drush:

drush en search_api_solr -y

For more information, see the Search API Solr module documentation.

Install the SearchStax Module

Install the SearchStax module with Composer:

composer require searchstax/searchstax

Enable the module using Drush:

drush en searchstax -y

For more information, see the SearchStax Drupal module documentation.

Install the Key Module

Install the Key module with Composer:

composer require drupal/key

Enable the module using Drush:

drush en key -y

For more information about the module, see the Drupal Key documentation.

Once you complete these setup tasks, you're ready to configure Drupal to use the Key module with SearchStax.

Step 1: Create a Key for the SearchStax Server

1. In Drupal, go to Configuration → System → Keys.
2. Click Add key.
3. Configure the key:
   • Key name: For example, searchstax_api_key
   • Key type: Authentication
   • Key provider: File
   • File location: private://keys/file-key-connection.txt
4. Click Save.

At this point, Drupal knows where the key is stored, but the secret value isn't saved in the database.

Step 2: Create the Key File

Create the file at the location you specified when defining the key. The file must contain valid JSON.

For example:

{
  "update_endpoint": "https://searchcloud.example.searchstax.com/12345/example/update",
  "update_token": "<your-update-token>",
  "bashsuggest_core": "<your-bashsuggest-core>"
}

The bashsuggest_core value is optional.

Note: If the JSON structure or field names change, SearchStax may not be able to read the credentials correctly.

Step 3: Create or Update the SearchStax Server

1. In Drupal, go to Configuration → Search and metadata → Search API.
2. Select Add server, or open an existing SearchStax server for editing.
3. Set the backend to SearchStax.
4. Under the SearchStax connector settings, choose the credentials source:
   • Do not use Key module: Enter the connection values directly in the fields.
   • SearchStax analytics credentials: Select the analytics credentials key you want to use.
   • SearchStax connector credentials: Select the connector credentials key you created in step 1.
5. Complete the remaining server settings, then select Save.

You can switch between these options based on your setup. If the Key module is not installed, Drupal shows only the direct entry fields.

Step 4: Create a Key for SearchStax Module Settings

1. Create a new file in a secure location.

2. Add the SearchStax analytics credentials in JSON format. 
   
   For example:

   {
     "analytics_url": "https://app.searchstax.com",
     "analytics_key": "<your-analytics-key>"
   }

3. Go to Configuration → System → Keys and create a new key that points to this file.
4. Go to Configuration → Search and metadata → SearchStax.
5. Select the new key in the SearchStax settings. If you don't want to use the key, select Do not use Key module, then enter the Analytics URL and Global Analytics Key fields directly.
6. Click Save.

If the Key module isn't installed, Drupal displays only the direct entry fields.