Diagnose customer integration issues

Use this guide when an Aura Home embed does not load, authenticate, render, or pass launch validation in a customer portal.

Quick Checks

Open the configured baseUrl directly in a browser tab.
Confirm the portal page, runtime, SDK assets, and identity endpoints all use HTTPS.
Check the browser console for CSP, framing, mixed-content, or certificate errors.
Confirm the token callback returns a valid OIDC/JWT token.
Listen for SDK loaded, ready, configAck, tokenProvided, and error events.

Symptoms and Fixes

Symptom	Likely Cause	Fix
Iframe is blank	Runtime URL is wrong, blocked, or not allowed to frame.	Open `baseUrl` directly, check runtime allowlists, and inspect browser console framing errors.
SDK cannot find container	`AuraHome.init` runs before the container exists.	Create `<div id="aura-home"></div>` before initialization or initialize after the component mounts.
`ready` never fires	Runtime loaded but did not complete SDK handshake.	Check `allowedOrigin`, runtime availability, and console errors inside the iframe if accessible.
SSO returns 401	Missing, expired, or invalid token.	Validate `iss`, `aud`, `sub`, `exp`, signature, and runtime OIDC configuration.
SAML works but Aura Home is anonymous	SAML session was not bridged into an OIDC/JWT token.	Exchange the SAML session through the customer identity gateway and return the OIDC/JWT token from `getToken`.
Mixed-content warning	One script, iframe, API, stylesheet, or image uses HTTP.	Move all integration URLs to HTTPS.
Certificate warning	Expired certificate, wrong SAN, or incomplete chain.	Renew or reissue the certificate and serve the full chain from the edge.
Theme does not apply	The requested `theme.id` is not allowed, CSS variable names are invalid, or hosted stylesheet is blocked.	Confirm the runtime allowlist or dashboard-published appearance profile, use variables starting with `--`, and allow the stylesheet URL in CSP.

Debug Event Snippet

const aura = AuraHome.init({
  container: "#aura-home",
  baseUrl: "https://aura.customer-domain.com/",
  allowedOrigin: "https://aura.customer-domain.com",
  auth: {
    mode: "oidc",
    getToken: async () => customerIdentity.getIdToken()
  }
});

["loaded", "ready", "configAck", "tokenProvided", "error"].forEach((eventName) => {
  aura.on(eventName, (event) => {
    console.info("[Aura Home]", eventName, event);
  });
});

What to Send Cadisa Support

Portal URL and Aura Home runtime URL.
Environment name: development, staging, or production.
Browser console errors, with tokens and secrets removed.
Network status for the iframe runtime and SDK assets.
Token claim summary: issuer, audience, expiry, and subject presence only. Do not send raw tokens.