Usually anyone can query any AddSearch index by just knowing the public key of that index. In most cases this is not a problem, since the index contains only information publicly available on the customer’s website. In some cases it would be useful to be able to limit the access to the index though, for example when indexing the contents of your intranet. One way you could do this is by implementing the search with our API, proxying all requests from the browser through your backend. This way you can avoid exposing your public key to the end user. It’s not perfect though – for one, it’s more work than using one of our ready made javascript widgets. A better solution is to configure your index to require JWT token authentication.

AddSearch JWT authentication

JWT authentication works with the following principles:

  1. Once the index is configured to require JWT, both API requests and requests from widget will fail unless the token is correctly included in the request
  2. The customer generates and sign the JWT token in their backend and passes it on to the page where the search is located
  3. The search page injects the JWT token to the widget using widget settings
  4. The widget uses the given JWT token for subsequent search requests
  5. The AddSearch index will validate the signature and both “issued at” and “expiry” fields, and return the search results only if the validation is successful

To enable JWT on your search index, please contact our support via support@addsearch.com. This feature is available for AddSearch Premium and Enterprise plans.

Generating the JWT token

The header of the JWT token should be:

{
  "typ": "JWT",
  "alg": "HS256"
}

An example of the JWT payload:

{
  "public_key": "abc123",
  "exp": 1560282114,
  "iat": 1560253314,
  "jti": "1234"
}

Field explanations:

  • public_key The public key of your index
  • jti An unique ID for this search session
  • iat “Issued at” – a standard JWT issued at time in POSIX “Seconds Since the Epoch” format
  • exp The expiry time of the token in same format as iat. Maximum expiry time is 24 hours after iat. A recommended value is something fairly short like 1 minute.

You can generate JWT tokens using the debugger tool on https://jwt.io/. The site also lists a wide variety of JWT libraries for different programming languages. Here is an example of generating a JWT token for AddSearch search widget in Java:

import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;
import com.auth0.jwt.exceptions.JWTCreationException;

import java.time.LocalDateTime;
import java.time.ZoneId;
import java.util.Date;

class Scratch {
  public static void main(String[] args) {
    try {

      // use AddSearch index secret key as the signing key
      Algorithm algorithm = Algorithm.HMAC256("d3b07384d113edec49eaa6238ad5ff00");

      String token = JWT.create()
              .withIssuedAt(Date.from(LocalDateTime.now().atZone(ZoneId.systemDefault()).toInstant()))
              .withExpiresAt(Date.from(LocalDateTime.now().plusMinutes(5).atZone(ZoneId.systemDefault()).toInstant()))
              // AddSearch index public
              .withClaim("public_key", "c157a79031e1c40f85931829bc5fc552")
              // An unique ID for this token generated by the customer
              .withJWTId("123")
              .sign(algorithm);

      System.out.println(token);

    } catch (JWTCreationException exception) {
    }
  }
}

Injecting JWT token to AddSearch widget

Once you have generated the JWT token in your backend and made it available on your search page, you can inject it to the AddSearch search widget like so:

<!-- AddSearch settings -->
<script>
window.addsearch_settings = {
  jwt: 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwdWJsaWNfa2V5IjoiYWJjMTIzIiwiZXhwIjoxNTYwMjgyMTE0LCJpYXQiOjE1NjAyNTMzMTQsImp0aSI6IjEyMzQifQ.hrKgqGnzHSYSaWYo3A91uWzWmbEZxII9GV5-2uxo6T4'
}
</script>
 
<!-- This script must be below addsearch_settings -->
<script src="https://addsearch.com/js/?key=####"></script>

Using addsearch_settings is described in more detail here.

Note that when using a short expiry value in the token (as recommended), you should re-generate the token before the expiry runs out, and set it again to the addsearch_settings object.