Using JWT tokens to secure search

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 access to the index, 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"
}

The token needs to be signed with your AddSearch secret key using the HMAC256 algorithm.

Field explanations:

• public_key The public key of your index
• jti A unique ID for this search session
• iat “Issued at” – a standard JWT issued at the time in POSIX “Seconds Since the Epoch” format
• exp The expiry time of the token in the same format as iat. The 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("your_addsearch_secret_key"); 
      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", "your_addsearch_public_key") 
      // A 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 ready-made views

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 = {
  "asw_01": {
    ...
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwdWJsaWNfa2V5IjoiYWJjMTIzIiwiZXhwIjoxNTYwMjgyMTE0LCJpYXQiOjE1NjAyNTMzMTQsImp0aSI6IjEyMzQifQ.hrKgqGnzHSYSaWYo3A91uWzWmbEZxII9GV5-2uxo6T4"
  }
} 
</script>

You can find more details on how the ready-made settings are configured in the Search Designer.

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.

Set JSON Web Token (for authentication)

You can use the AddSearch Search API Client for JavaScript to set the JSON Web Token for authentication.

// Add JWT to the search request (if protected search index)
client.setJWT(token);

Visit the AddSearch Search API Client for JavaScript reference pages at Github and npmjs.