Embedding & White-Label

EUnifyer is built to live inside your product. A partner portal, an education platform, or a managed-workplace suite can present EUnifyer’s modules — Drive, Mail, Calendar, Chat — as if they were native features, branded as your own.

Everything below is self-service from Admin → Integration (the Partner Integration hub). No YAML, no redeploy, no support ticket.

Three integration models

There is no single “right” way to integrate — pick per module, or mix them.

Models A and B share the same sign-in session, so a user who is signed in once reaches every surface.

Model B — Embedding

How it works

Each embeddable module is served at a minimal-chrome route — no global navigation, just the module:

Your portal frames these in an <iframe>. Two things make it safe and seamless:

1. A host allowlist decides who may frame you (enforced by the browser via the CSP frame-ancestors directive).
2. Shared authentication means the framed module is already signed in — no second login inside the frame.

Only the modules enabled in your deployment are embeddable. Modules your plan or deployment does not include have no /embed/* route at all.

1. Allow your portal to frame EUnifyer

Open Admin → Integration → Embedding and add the web address of the portal that will embed EUnifyer — for example https://workplace.example.com. Only listed origins may frame your modules; everything else is blocked by the browser.

• The allowlist is enforced as a CSP frame-ancestors directive on the /embed/* pages.
• Changes take effect within ~60 seconds — no redeploy.
• Use the exact origin (scheme + host + port). https://workplace.example.com and http://localhost:8080 are different origins.

Self-hosted / sovereign deployments can also seed deployment-wide trusted hosts with the EMBED_FRAME_ANCESTORS setting. The effective allowlist is the union of that and every organisation’s self-service hosts.

2. Copy a snippet

The Embedding tab generates a ready-to-paste snippet per module. Drop it into your portal where you want the module to appear:

<iframe
  src="https://app.example.com/embed/drive"
  style="width:100%;height:100%;border:0"
  allow="clipboard-read; clipboard-write"
></iframe>

A live preview in the hub shows exactly how the module renders before you ship it.

White-label theming

White-label is per-organisation theme tokens — not a fork, not a separate build. Set your logo, name, colours, and fonts once and every surface (the full app, branded login pages, and embedded modules) reads as your brand, not EUnifyer’s.

Configure it under Admin → Integration → “Make it yours” (or Admin → Settings → Branding):

• Logo and product name
• Brand colour(s) and fonts
• Branded login pages (logo, colours, custom domain)

Because the theme is applied from the organisation’s tokens, an embedded Drive inside workplace.example.com looks like Example Workplace — same component, your skin.

Authentication inside an embed

The framed module needs to know who the user is. EUnifyer supports two handoff models — prefer the first.

(a) Shared SSO session — recommended

The iframe rides the EUnifyer session cookie. For cross-site framing the cookie must be issued SameSite=None; Secure so the browser includes it inside a third-party frame. When the user is already signed in to EUnifyer, the embedded module is authenticated automatically — no token passes through JavaScript.

(b) Token handoff — fallback

For hosts that cannot share a cookie (or browsers that block third-party cookies), the host relays a short-lived EUnifyer access token to the iframe. The token can be delivered two ways:

• postMessage — the host posts { type: "eunify-embed-auth", token } to the iframe.
• URL fragment — load the frame with src=".../embed/drive#eu_token=<token>"; the token is consumed and stripped from history.

Tokens are only accepted from a real framing ancestor (validated via the browser’s ancestorOrigins), never from an arbitrary opener.

postMessage protocol

The embedded module talks to the host with a small message protocol:

A minimal host that drops a spinner when the module is ready and (optionally) hands a token:

<script>
  const FRAME_ORIGIN = "https://app.example.com";
  window.addEventListener("message", (e) => {
    if (e.origin !== FRAME_ORIGIN) return;
    if (e.data?.type === "eunify-embed-ready") {
      // module mounted — hide your loading overlay
      // optional token handoff:
      // frame.contentWindow.postMessage({ type: "eunify-embed-auth", token }, FRAME_ORIGIN);
    }
    // e.data.height is available on "eunify-embed-resize" for auto-sizing
  });
</script>

Requirements & gotchas

• frame-ancestors, not X-Frame-Options. EUnifyer drops X-Frame-Options on /embed/* (it cannot express an allowlist) and relies on the CSP directive instead.
• Cross-site cookies need SameSite=None; Secure. Verify in the actual browser you will demo in — some browsers block third-party cookies by default, in which case use the token handoff. A same-origin preview (the hub’s live preview) always works.
• The secure-mail public portal is never embeddable — it stays frame-ancestors 'none' regardless of the allowlist.
• Use HTTPS in production. Secure cookies are only sent over HTTPS.

Setup checklist

1. Brand it — set logo, name, colours, fonts (Make it yours).
2. Connect sign-in — federate your IdP so users sign in once. See Identity & SSO.
3. Embed modules — add your portal’s host to the allowlist, copy a snippet, verify in the live preview.
4. Developer access — for headless (Model C) needs, issue API keys and subscribe to webhooks. See Developer API and Webhooks.