Using embed secrets (JWTs)

​

What are Embed Secrets?

Embed secrets are a key id, key value pair that allow you to generate JWTs to embed your dashboards. The JWT Explo uses is a JWT with a JWE body. You can find more information about JWTs at this link. You would use this token the same way you use your dashboard id, customer token pair, but the token has two extra functions:

• Hides this dashboard id and customer token from your customers
• Expires at a cadence you set (default is one day)

​

Generating a JWT

​

Generate the Embed Secret

First, you must generate an embed secret. Go to the Data Visibility Groups section in the settings page, create a new secret, and copy your secret’s value and id. Then, you have two options:

​

Use Explo’s API to generate the JWT

For convenience, Explo exposes an endpoint you can use to generate a JWT for your customer/dashboard pair. You could hit this endpoint when your customer loads the page and provide the JWT immediately to your embedded component.

See here for docs on this endpoint

​

Manually generate the JWT

You can also generate the JWT yourself. The specs of the JWT are as follows

Claims:

• cst: your customer id, the one you provided to Explo
• dsh: your embed id, taken from the Explo app
• exp: the desired expiration timestamp
• kid: the key id you’re using to sign and encrypt the jwt
• alg: A256GCM

# A python example:
from jose import jwe

jwt = jwe.encrypt(
  json.dumps(
      {
          "exp": (datetime.utcnow() + timedelta(hours=2)).timestamp(),
          "cst": "customer_1",
          "dsh": "abcdef",
      }
  ),
  encryption="A256GCM",
  key=key_value,
  kid=key_id,
).decode("utf-8")

// A javascript example:
import * as jose from "jose";

const enc = new TextEncoder();
const secret = enc.encode(key_value);

const jwt = new jose.EncryptJWT({
  cst: "customer_1",
  dsh: "abcdef",
})
  .setProtectedHeader({ alg: "dir", enc: "A256GCM", kid: key_id })
  .setIssuedAt()
  .setExpirationTime("2h")
  .encrypt(secret);

​

Testing an Embedded Dashboard or Report Builder

You can use Explo’s Embed Modal to generate a JWT for testing purposes. The JWT will be generated using a test Embed Secret. Note that this JWT will expire after 24 hours, so it should not be used in production.

On the Dashboard Page or on the Report Builder Page, select the dashboard or report builder you’d like to embed and click the Embed option from its menu. Select a customer from the dropdown and the JWT will be automatically generated and inserted into the resulting code snippet.

​

Refreshing an expired JWT

When your JWT expires, the embedded session will stop working, which means that no new data can be loaded without first creating a new JWT. Depending on how you’ve implemented your dashboards, you may be generating a new JWT when your customer refreshes the page. But if you want to create JWTs with short expiration times and want to avoid requiring your users to refresh on expiration, you can add an event listener to be notified when the JWT is about to expire and respond with a new one.

For more information, see the examples below, or our documentation on Custom Events

​

Iframe

const messageListener = (e) => {
  switch (e.data.event) {
    case "customerJwtExpired":
      // generate a new JWT here
      const jwt = "my-new-jwt";

      var exploIframe = document.getElementById("explo-iframe");
      exploIframe.contentWindow.postMessage(
        {
          event: "updateCustomerJwt",
          detail: { jwt },
        },
        "*"
      );
      break;
  }
};

window.addEventListener("message", messageListener);

​

Web Component

const listener = (e) => {
  // generate a new JWT here
  const jwt = "my-new-jwt";

  window.dispatchEvent(
    new CustomEvent("updateCustomerJwt", { detail: { jwt } })
  );
};

window.addEventListener("customerJwtExpired", listener);