API Keys/security
On this page
You are reading the documentation for Angular InstantSearch v3, which is in beta. You can find the v2 documentation here.
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 Angular 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.
1
2
3
4
5
6
7
8
9
const algoliasearch = require('algoliasearch');
const client = algoliasearch('YourSearchOnlyAPIKey', '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
If you have used Angular CLI to generate your application, you most likely have an index.html in /src directory of you project. To inject data from the server we can use a placeholder value (this link is for Create React App, but also applies in the case of Angular) in the HTML.
1
2
3
4
5
6
7
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<script>
window.SERVER_DATA = __SERVER_DATA__;
</script>
After the build, this index.html file will later be put in the /dist directory, where express is going to serve it from.
Once the placeholder is set up, we can replace it with the generated API Key.
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, '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. Take a look at the next section to learn how to use this key in the Angular 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import algoliasearch from 'algoliasearch/lite';
@Component({
template: `
<ais-instantsearch [config]="config">
<!-- Widgets -->
</ais-instantsearch>
`,
})
export class AppComponent {
config = {
indexName: 'demo_ecommerce',
searchClient: algoliasearch('AJ0P3S7DWQ', (window as any).SERVER_DATA.ALGOLIA_API_KEY),
}
}
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></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.
To fix this, Angular 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 mark. If you want to use another one, like for example strong, you need to specify the tagName attribute.
1
2
3
4
5
6
7
8
9
<ais-instantsearch [config]="config">
<ais-hits>
<ng-template let-hits="hits" let-results="results">
<div *ngFor="let hit of hits">
<ais-highlight attribute="name" tagName="strong" [hit]="hit"></ais-highlight>
</div>
</ng-template>
</ais-hits>
</ais-instantsearch>
