JWT Embedding

JWT embedding is the standard authentication method for embedded analytics. A JSON Web Token (JWT) is a compact, signed payload that the host application generates and passes to the embedded BI component. The BI tool verifies the token's signature, reads the claims inside it, and enforces access controls – all without needing a direct connection to the host app's user database.

The token is self-contained. It carries everything the BI tool needs to authenticate the user and determine what data they can see. No session cookies, no database lookups, no user sync pipelines. That stateless quality is why JWT became the default for embedded analytics rather than alternatives like OAuth flows or API key schemes.

How the flow works

The sequence is the same across virtually every embedded analytics implementation:

1. User authenticates with the host application. The user logs into your product through your normal auth flow – username/password, SSO, whatever you use.

2. Host app generates a JWT. Your backend creates a signed token containing claims about the user – who they are, what tenant they belong to, what they're allowed to see.

3. Token passes to the embedded component. The frontend sends this token to the embedded dashboard or portal, typically as a URL parameter or in the iframe initialization call.

4. BI tool verifies and enforces. The BI tool checks the token's signature against the shared secret or public key, validates expiration, reads the claims, and applies the appropriate data access rules.

The entire handoff happens in milliseconds. The user sees a dashboard. They never interact with the BI tool's auth system directly.

What claims typically include

JWT claims are key-value pairs that describe the user and their access context. A typical embedded analytics token carries:

• User identifier – email address or user ID from the host application.
• Tenant identifier – the organization or account the user belongs to, used for row-level security filtering and data routing.
• Role or permission level – admin, viewer, analyst. Controls which dashboards or features the user can access.
• Custom attributes – region, plan tier, department, or any other user attributes that drive filtering or personalization.
• Token metadata – issued-at timestamp, expiration time, issuer identifier.

The claims you include depend on your data model and access control requirements. A simple single-tenant embed might only need a user ID and expiration. A multi-tenant SaaS product with role-based access needs the full set.

Security considerations

JWTs are signed but unencrypted by default. The payload is base64-encoded – anyone can decode and read it. This means you should avoid putting sensitive information like passwords or secret keys in the claims.

Signing algorithm matters. Use asymmetric algorithms (RS256, ES256) in production. Symmetric signing (HS256) works but means the BI tool and your application share the same secret – a compromise on either side exposes the other.

Token expiry is non-negotiable. Short-lived tokens – minutes rather than hours – limit the blast radius if a token is intercepted. The host application should generate a fresh token for each session or embed load.

Claim validation must be strict. The BI tool should validate every claim it uses for access control. A token that claims tenant_id=acme should only return data for Acme. If the BI tool reads claims but fails to enforce them at query time, the JWT is decoration rather than security.

Why JWT is the standard

JWT won the embedded analytics auth pattern for three reasons. It's stateless – no session store or user database sync needed between the host app and the BI tool. It's portable – the same token format works across languages, frameworks, and platforms. And it's expressive – the claims mechanism lets you pass arbitrary user context that drives everything from data filtering to UI personalization, all in a single signed payload.