Secured API Keys in React InstantSearch

Search-Only API Keys on web

Inside your application you can use the search-only API Key. You can include this key directly in your front-end code. It might happen that you need to apply some rate limiting to your API Key. For those cases, you can generate what we call Secured API Keys.

Secured API Keys

Secured API Keys are useful when you want to restrict the search to a set of indices, for example. Those keys need to be generated on the back-end. Otherwise, users can modify the restrictions of the key by modifying the front-end code. There is already a tutorial about how to use Secured API Keys, but this guide will focus on the usage of those keys inside a InstantSearch application. We will implement an application that generates a secured API Key on the server, then uses it on the client. The secured API Key will have a restriction on the index. You can find the complete example on GitHub.

Server

Generate the Secured API Key

The first step is to generate our Secured API Key on the server. In this example we are using Express but the concepts could be applied to any server. To generate our key we need the Algolia JavaScript client and a “parent key” that has the search ACL. Most of the time this “parent key” will be the search-only API Key. In this example we restrict our key to the index demo_ecommerce. It means that with this key the front end won’t be able to target a different index. You can apply different kind of restrictions and also apply a set of search parameters.

Copy
const algoliasearch = require('algoliasearch');

const client = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');
const securedApiKey = client.generateSecuredApiKey('YourSearchOnlyAPIKey', {
  restrictIndices: 'demo_ecommerce',
});

Once we have the key we need to pass it down to our client. We have the choice between two different implementations:

create an endpoint on your server that will send back the API Key. Then on the client before creating the application you need to asynchronously fetch the API key from the server.
inline the API key in the HTML. Then on the client we can directly create the application by reading the value from the global object.

In this guide we will go for the second option: inline the API Key.

Inline the API Key

For simplicity, in this example we use Parcel. But with Parcel we don’t create the HTML file from scratch, we use the one generated by the CLI. To inject data from the server we can use a placeholder value in the HTML. Note that this step is only useful if you are using an application generated from a CLI. Otherwise you can directly inline the value inside your HTML template.

Copy
<!DOCTYPE html>
<html lang="en">
  <head>
    <script>
      window.SERVER_DATA = __SERVER_DATA__;
    </script>
  </head>
</html>

Once the placeholder is setup we can replace it with the generated API Key.

Copy
const path = require('path');
const fs = require('fs');
const util = require('util');
const express = require('express');

const app = express();
const readFileAsync = util.promisify(fs.readFile);

app.get('/', async (_, res) => {
  const index = await readFileAsync(
    path.join(__dirname, 'dist', 'index.html'),
    'utf-8'
  );

  const indexWithServerData = index.replace(
    '__SERVER_DATA__',
    JSON.stringify({
      ALGOLIA_API_KEY: securedApiKey,
    })
  );

  res.send(indexWithServerData);
});

That’s it for the server. You should now be able to run the server and access your generated API key from the client with window.SERVER_DATA. The next section of this guide describes how to use this key in an InstantSearch application.

Client

Retrieve the API Key

Now that you have the API key on the global object, you can retrieve it from the client code and inject it into searchClient. Make sure you clean up the global object; otherwise, this value will stay in memory.

Copy
import React from 'react';
import ReactDOM from 'react-dom';
import { InstantSearch } from 'react-instantsearch-dom';
import algoliasearch from 'algoliasearch/lite';

function App({ searchClient }) {
  return (
    <InstantSearch
      indexName="demo_ecommerce"
      searchClient={searchClient}
    >
      {/* Widgets */}
    </InstantSearch>
  );
}

const SERVER_DATA = window.SERVER_DATA;

// clean up the global object
delete window.SERVER_DATA;

const searchClient = algoliasearch(
  'YourApplicationID',
  SERVER_DATA.ALGOLIA_API_KEY
);


ReactDOM.render(
  <App searchClient={searchClient} />,
  document.getElementById('root')
);

That’s it for the client. Your application can now only target the index demo_ecommerce. You can try to target a different one like demo_media, but the API will return an error.

The complete example is on GitHub.

See live demo

XSS - Preventing attacks from within user generated content.

Algolia handles highlighting within the engine. By leveraging this feature, you give your user a way to know how their query matches the results, it is a very important cue.

Technically this means that the engine will surround the matching words with tags. By default, we use simple HTML tags like em and we let the browser render the content as HTML. This leaves a potential security hole, especially in the context of user generated content.

The same problem exists for the snippeting feature.

To fix this, InstantSearch will force the use of a known set of HTML tags and will escape all tags not in this set. This means that if you’ve set a custom tag in the Algolia Dashboard, it will be overridden and replaced by mark. If you want to use another one, like for example strong, you need to specify the highlightedTagName props in Highlight or Snippet.

Copy
import React from 'react';
import {
  InstantSearch,
  Hits,
  Highlight,
  Snippet,
} from 'react-instantsearch-dom';

const Hit = ({ hit }) => (
  <p>
    <Highlight attribute="name" hit={hit} tagName="mark" />
    <Snippet attribute="description" hit={hit} tagName="mark" />
  </p>
);

const App = () => (
  <InstantSearch
    indexName="instant_search"
    searchClient={searchClient}
  >
    <Hits hitComponent={Hit} />
  </InstantSearch>
);

Conditional requests

API keys/security

Did you find this page helpful?