Skip to main content

Securing AddSearch Search with JWT Authentication

By default, anyone can query an AddSearch index using its public key. This typically works when your indexed content is publicly available on your website. However, if you want to restrict access—such as when indexing an intranet or sensitive content—you can secure your index using JWT (JSON Web Token) authentication.

Overview of JWT Authentication with AddSearch​

When you enable JWT authentication on your index:

  1. All search requests (both via API and widgets) require a valid JWT token. Requests without it will fail.
  2. You generate and sign JWT tokens on your backend server.
  3. Your frontend search page receives the JWT token and injects it into the AddSearch widget.
  4. The widget includes the JWT token in all search requests.
  5. AddSearch validates the token's signature, issued-at (iat), and expiry (exp) times before returning results.

Note: To activate JWT authentication on your index, contact AddSearch support at support@addsearch.com. This feature is available for Advanced and Enterprise plans.

Generating JWT Tokens​

Your backend must create JWT tokens signed with your AddSearch secret key using the HS256 algorithm.

JWT Header​

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

JWT Payload Example​

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

Payload Field Descriptions​

  • public_key: The public key of your AddSearch index.
  • iat: Issued At — the timestamp (in POSIX seconds) when the token was created.
  • exp: Expiry — the timestamp (in POSIX seconds) when the token expires. Maximum expiry is 24 hours after iat. A recommended expiry time is short (e.g., 1 minute).
  • jti: JWT ID — a unique identifier for the token or search session.

Signing the Token​

Use your AddSearch secret key to sign the token with HMAC SHA-256. You can use JWT libraries available for most programming languages.

Generating Tokens Example 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;

public class GenerateJWT {
  public static String createToken(String secretKey, String publicKey, String jti) {
    try {
      Algorithm algorithm = Algorithm.HMAC256(secretKey);
      Date issuedAt = Date.from(LocalDateTime.now().atZone(ZoneId.systemDefault()).toInstant());
      Date expiresAt = Date.from(LocalDateTime.now().plusMinutes(5).atZone(ZoneId.systemDefault()).toInstant());

      return JWT.create()
          .withIssuedAt(issuedAt)
          .withExpiresAt(expiresAt)
          .withClaim("public_key", publicKey)
          .withJWTId(jti)
          .sign(algorithm);
    } catch (JWTCreationException e) {
      // Handle token creation error
      e.printStackTrace();
      return null;
    }
  }
}

Testing and Tools​

Use https://jwt.io/ to debug and test token creation. It also provides libraries for multiple languages.

Injecting JWT Tokens into AddSearch Widgets​

Add the generated JWT token to your frontend page and pass it to the AddSearch widget configuration.

Example:​

<script>
window.addsearch_settings = {
  "asw_01": {
    // ... other settings ...
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwdWJsaWNfa2V5IjoiYWJjMTIzIiwiZXhwIjoxNTYwMjgyMTE0LCJpYXQiOjE1NjAyNTMzMTQsImp0aSI6IjEyMzQifQ.hrKgqGnzHSYSaWYo3A91uWzWmbEZxII9GV5-2uxo6T4"
  }
};
</script>

You can adjust the jwt value dynamically each time the page loads or before the token expires.

Important: With short token expiry times (recommended), regenerate and update the JWT token regularly to avoid authentication failures during active search sessions.

For more details about configuring the widget settings, visit the Search Designer.

Using JWT with the AddSearch JavaScript Client Library​

If you use the AddSearch JavaScript client library instead of ready-made widgets, set the JWT token explicitly:

// Assuming 'client' is your AddSearch client instance
client.setJWT(token);

Refer to the client library documentation for implementation details: