Concepts / Building Search UI / API keys/security
Aug. 06, 2019

API Keys/security

On this page

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 React 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
1
2
3
4
5
6
7
8
9

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 mounting 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 mount 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 Create React App (CRA). But with CRA 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 CRA. Otherwise you can directly inline the value inside your HTML template.

Copy
1
2
3
4
5
6

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

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

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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, 'build', '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. Take a look at the next section to learn how to use this key in the React InstantSearch application.

Client

Retrieve the API Key

Now that we have the API Key on the global object we can retrieve it from our client code and inject it into our searchClient. Don’t forget to clean up the global object otherwise this value will stay in memory.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import React from 'react';
import ReactDOM from 'react-dom';
import algoliasearch from 'algoliasearch/lite';
import App from './App';
import './index.css';

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')
);

Use the injected searchClient

The last part is to use the injected searchClient in our React application.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

class App extends Component {
  static propTypes = {
    searchClient: PropTypes.object.isRequired,
  };

  render() {
    const { searchClient } = this.props;

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

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. Don’t forget to take a look at the complete example on GitHub.

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 tags and will escape all the other HTML tags. This means that if you’ve set a custom tag in the Algolia Dashboard it will be overridden and replaced by em. If you want to use another one, such as the more semantically correct mark, you need to specify the highligtedTagName parameter in Highlight or Snippet.

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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>
);

Did you find this page helpful?

React InstantSearch v5