So integrieren Sie Ihre App als iframe in B2CORE

Erfahren Sie, wie Sie eine Webanwendung eines Drittanbieters als iframe in B2CORE integrieren, einschließlich Serverkonfiguration, Synchronisierung von Theme und Sprache sowie JWT-basierter Authentifizierung über die postMessage-API

B2CORE unterstützt das direkte Einbetten von Webanwendungen Dritter in die Kunden-Benutzeroberfläche über ein iframe. Wenn ein benutzerdefinierter Menüpunkt mit dem Verhalten Iframe konfiguriert ist, lädt B2CORE Ihre Anwendung innerhalb der Benutzeroberfläche und bietet Kunden ein nahtloses Erlebnis, ohne die Plattform zu verlassen.

Dieser Leitfaden behandelt zwei Aspekte: die Konfiguration des benutzerdefinierten Menüpunkts im B2CORE Back Office und die Vorbereitung Ihrer Anwendung für die korrekte Funktion innerhalb des B2CORE-iframe.

Voraussetzungen

Stellen Sie vor dem Fortfahren Folgendes sicher:

Schritt 1. Konfigurieren Sie Ihren Server, um die Einbettung in iframes zuzulassen

Standardmäßig verhindern die meisten Webserver und Frameworks, dass Seiten in iframes auf anderen Domains eingebettet werden. Damit B2CORE Ihre Anwendung laden kann, müssen Sie die entsprechenden HTTP-Antwort-Header auf Ihrem Server konfigurieren.

Sie müssen einen oder beide der folgenden Header festlegen:

Content-Security-Policy

Der Header Content-Security-Policy mit der Direktive frame-ancestors steuert, welche Origins Ihre Seite einbetten dürfen. Legen Sie diesen Header so fest, dass er die Origin Ihrer B2CORE-Instanz einschließt:

Content-Security-Policy: frame-ancestors 'self' https://portal.example.com

Ersetzen Sie https://portal.example.com durch die tatsächliche Origin der von Ihren Kunden verwendeten B2CORE-Benutzeroberfläche. Sie können mehrere Origins, durch Leerzeichen getrennt, angeben, wenn Ihre Anwendung in mehreren B2CORE-Instanzen eingebettet werden muss.

Weitere Informationen finden Sie in der Content-Security-Policy-Dokumentation auf MDN.

X-Frame-Options

Der Header X-Frame-Options ist ein älterer Mechanismus mit einem ähnlichen Ergebnis. Wenn Sie ihn verwenden, setzen Sie ihn mit Ihrer B2CORE-Origin auf ALLOW-FROM:

X-Frame-Options: ALLOW-FROM https://portal.example.com

Die Direktive X-Frame-Options: ALLOW-FROM wird nicht von allen Browsern unterstützt. Es wird empfohlen, den Header Content-Security-Policy mit der Direktive frame-ancestors als primären Mechanismus zu verwenden und X-Frame-Options nur als Fallback für ältere Kunden einzuschließen.

Weitere Informationen finden Sie in der X-Frame-Options-Dokumentation auf MDN.

Schritt 2. Fügen Sie einen benutzerdefinierten Menüpunkt im B2CORE Back Office hinzu

Um Ihre Anwendung für Kunden zugänglich zu machen, fügen Sie einen benutzerdefinierten Menüpunkt mit dem iframe-Verhalten hinzu:

Navigieren Sie zu Promotion > Menu.

Klicken Sie auf das Symbol Auge in der Zeile General, um die Menüstruktur anzuzeigen.

Klicken Sie in der oberen rechten Ecke der Seite auf +Create.

Füllen Sie die erforderlichen Felder aus:

  • Geben Sie im Feld Name einen eindeutigen Namen für den Menüpunkt ein.
  • Geben Sie im Feld Caption die Bezeichnung ein, die Kunden im Menü sehen werden.
  • Geben Sie im Feld External URL die URL Ihrer Anwendung an.
  • Geben Sie im Feld Icon die URL eines SVG-Symbols an (16x16 px, einfarbig, transparenter Hintergrund).
  • Wählen Sie in der Dropdown-Liste Custom Behavior die Option Iframe.

Konfigurieren Sie bei Bedarf optionale Einschränkungen:

  • Um die Sichtbarkeit auf bestimmte Verifizierungsstufen zu beschränken, wählen Sie die entsprechenden Stufen in der Dropdown-Liste Verification Level Allowance aus.
  • Um die Sichtbarkeit auf bestimmte Kundentypen zu beschränken, wählen Sie die entsprechenden Typen in der Dropdown-Liste Client Type Allowance aus.

Aktivieren Sie das Kontrollkästchen Visible, damit der Eintrag im Menü angezeigt wird.

Klicken Sie auf Save, um den benutzerdefinierten Menüpunkt hinzuzufügen.

Wenn Kunden auf diesen Menüpunkt klicken, wird Ihre Anwendung innerhalb eines iframe in der B2CORE-Benutzeroberfläche geladen.

Für benutzerdefinierte Menüpunkte stehen zwei weitere Verhaltensoptionen zur Verfügung: Same tab (öffnet die URL im aktuellen Browser-Tab) und New tab (öffnet die URL in einem neuen Browser-Tab). Die iframe-Option ist die einzige Option, die Ihre Anwendung innerhalb der B2CORE-Benutzeroberfläche einbettet.

Schritt 3 (optional). Implementieren Sie das postMessage-Kommunikationsprotokoll

Wenn Ihre Anwendung den authentifizierten B2CORE-Benutzer identifizieren, das Theme der B2CORE-Benutzeroberfläche übernehmen oder der vom Benutzer ausgewählten Sprache folgen muss, können Sie das unten beschriebene postMessage-Kommunikationsprotokoll implementieren. Dieser Schritt ist optional — wenn Ihre Anwendung keine Benutzerauthentifizierung, Theme-Synchronisierung oder Sprachsynchronisierung benötigt, können Sie ihn überspringen.

Nachrichtenreferenz

Nachrichten von Ihrer Anwendung an B2CORE

NachrichtentypBeschreibungNutzlast
embed-iframe-readySignalisiert, dass das iframe geladen und bereit ist, Nachrichten zu empfangen.{ type: "embed-iframe-ready" }
embed-request-jwt-tokenFordert ein JWT-Authentifizierungstoken von B2CORE an.{ type: "embed-request-jwt-token" }

Nachrichten von B2CORE an Ihre Anwendung

NachrichtentypBeschreibungNutzlast
embed-theme-changeWird bei jeder Änderung des B2CORE-UI-Themes gesendet (und einmal direkt nach embed-iframe-ready).{ type: "embed-theme-change", theme: "dark-theme" | "light-theme" }
embed-language-changeWird bei jeder Änderung der B2CORE-UI-Sprache gesendet (und einmal direkt nach embed-iframe-ready).{ type: "embed-language-change", lang: "<language-code>" }
embed-jwt-tokenErfolgreiche Antwort auf eine Token-Anfrage.{ type: "embed-jwt-token", token: "<jwt-string>", expiresAt: "<ISO-8601>" }
embed-jwt-token-errorFehlerantwort, wenn die Token-Generierung fehlschlägt.{ type: "embed-jwt-token-error", error: "<error-message>" }
embed-logoutWird gesendet, wenn sich der B2CORE-Benutzer abmeldet. Jedes zuvor für Ihre App ausgestellte Token ist nun ungültig.{ type: "embed-logout" }

Das Feld lang enthält einen kleingeschriebenen Sprachcode nach ISO 639-1 (z. B. en, de, ar), der der aktuell in der B2CORE-Benutzeroberfläche ausgewählten Sprache entspricht.

Ein über embed-jwt-token ausgestelltes JWT-Token ist an den B2CORE-Benutzer gebunden, der zum Zeitpunkt der Ausstellung angemeldet war. Wenn sich dieser Benutzer abmeldet, sendet B2CORE embed-logout, und das Token darf nicht mehr verwendet werden. Verwerfen Sie alle zwischengespeicherten Token, beenden Sie geplante Aktualisierungen und löschen Sie benutzerspezifische Zustände, sobald Sie diese Nachricht erhalten. Wenn sich anschließend ein anderer Benutzer anmeldet, fordern Sie mit embed-request-jwt-token ein neues Token an — für den neuen Benutzer wird ein neues Token ausgestellt.

Kommunikationsablauf

Die Nachrichtenfolge zwischen Ihrer Anwendung und B2CORE folgt diesem Muster:

sequenceDiagram
    participant App as Your App (iframe)
    participant B2CORE as B2CORE (host)

    App->>B2CORE: embed-iframe-ready
    B2CORE-->>App: embed-theme-change (initial theme)
    B2CORE-->>App: embed-language-change (initial language)
    App->>B2CORE: embed-request-jwt-token
    alt success
        B2CORE-->>App: embed-jwt-token
    else failure
        B2CORE-->>App: embed-jwt-token-error
    end
    Note over App,B2CORE: Token nears expiry...
    App->>B2CORE: embed-request-jwt-token
    B2CORE-->>App: embed-jwt-token
    Note over App,B2CORE: User toggles theme...
    B2CORE-->>App: embed-theme-change
    Note over App,B2CORE: User changes language...
    B2CORE-->>App: embed-language-change
    Note over App,B2CORE: User logs out...
    B2CORE-->>App: embed-logout

Signalisieren Sie die Bereitschaft. Wenn das Laden Ihrer Seite abgeschlossen ist, senden Sie die Nachricht embed-iframe-ready an B2CORE. Dadurch wird dem Host mitgeteilt, dass Ihre Anwendung bereit ist, Daten zu empfangen.

Empfangen Sie das aktuelle Theme. B2CORE antwortet mit embed-theme-change, das das aktuelle Theme (dark-theme oder light-theme) enthält. Wenden Sie das Theme auf Ihre Benutzeroberfläche an. Sie erhalten diese Nachricht auch, wenn der Benutzer das Theme wechselt.

Empfangen Sie die aktuelle Sprache. B2CORE antwortet außerdem mit embed-language-change, das den aktuell in der B2CORE-Benutzeroberfläche ausgewählten Sprachcode enthält (z. B. en oder ar). Wenden Sie die entsprechende Gebietsschemaeinstellung auf Ihre Benutzeroberfläche an. Sie erhalten diese Nachricht erneut, wenn der Benutzer die Sprache ändert.

Fordern Sie ein Authentifizierungstoken an. Wenn Sie den aktuellen Benutzer identifizieren müssen, senden Sie embed-request-jwt-token. B2CORE antwortet entweder mit embed-jwt-token (das das JWT und seine Ablaufzeit enthält) oder mit embed-jwt-token-error, wenn die Token-Generierung fehlschlägt.

Aktualisieren Sie das Token vor Ablauf. Das JWT besitzt eine im Feld expiresAt angegebene Ablaufzeit (Format ISO 8601). Fordern Sie vor Ablauf des aktuellen Tokens ein neues Token an, um einen unterbrechungsfreien Zugriff zu gewährleisten.

Behandeln Sie die Abmeldung. Wenn sich der B2CORE-Benutzer abmeldet, sendet B2CORE embed-logout. Verwerfen Sie nach Erhalt das zwischengespeicherte Token, brechen Sie alle geplanten Aktualisierungen ab und löschen Sie benutzerspezifische Zustände, damit keine Daten an den nächsten Benutzer weitergegeben werden. Wenn sich danach ein anderer Benutzer anmeldet, fordern Sie mit embed-request-jwt-token ein neues Token an.

Codebeispiel

Ein vollständiges JavaScript-Snippet, das Sie in Ihre Anwendung einfügen können:

(function () {
  const B2CORE_ORIGIN = '*'; // Replace with your B2CORE instance origin for production

  let currentToken = null;
  let tokenRefreshTimer = null;

  // --- Send a message to B2CORE ---
  function sendToHost(message) {
    window.parent.postMessage(message, B2CORE_ORIGIN);
  }

  // --- Handle incoming messages from B2CORE ---
  function handleMessage(event) {
    const data = event.data;
    if (!data || !data.type) return;

    switch (data.type) {
      case 'embed-theme-change':
        applyTheme(data.theme);
        break;

      case 'embed-language-change':
        applyLanguage(data.lang);
        break;

      case 'embed-jwt-token':
        handleToken(data.token, data.expiresAt);
        break;

      case 'embed-jwt-token-error':
        console.error('Token error from B2Core:', data.error);
        break;

      case 'embed-logout':
        handleLogout();
        break;
    }
  }

  // --- Apply theme to your UI ---
  function applyTheme(theme) {
    document.documentElement.setAttribute('data-theme', theme);
  }

  // --- Apply language to your UI ---
  function applyLanguage(lang) {
    document.documentElement.setAttribute('lang', lang);
  }

  // --- Handle received JWT token ---
  function handleToken(token, expiresAt) {
    currentToken = token;

    // Schedule a refresh 2 minutes before expiry
    if (tokenRefreshTimer) {
      clearTimeout(tokenRefreshTimer);
    }

    const refreshIn = new Date(expiresAt).getTime() - Date.now() - 2 * 60 * 1000;

    if (refreshIn > 0) {
      tokenRefreshTimer = setTimeout(requestToken, refreshIn);
    } else {
      requestToken();
    }
  }

  // --- Request a JWT token from B2CORE ---
  function requestToken() {
    sendToHost({ type: 'embed-request-jwt-token' });
  }

  // --- Handle B2CORE user logout ---
  function handleLogout() {
    // The token is bound to the user who just logged out — stop using it.
    currentToken = null;

    if (tokenRefreshTimer) {
      clearTimeout(tokenRefreshTimer);
      tokenRefreshTimer = null;
    }

    // Clear any user-specific state in your app here.
  }

  // --- Initialize ---
  window.addEventListener('message', handleMessage);
  sendToHost({ type: 'embed-iframe-ready' });
  requestToken();
})();

Ersetzen Sie den Wert B2CORE_ORIGIN in der Produktion durch die tatsächliche Origin Ihrer B2CORE-Instanz (z. B. 'https://portal.example.com'). Die Verwendung von '*' ist nur während der Entwicklung akzeptabel, da dadurch jede Origin mit Ihrer Anwendung kommunizieren kann.

TypeScript-Typdefinitionen

Wenn Ihre Anwendung mit TypeScript erstellt wurde, können Sie die folgenden Typdefinitionen verwenden:

type EmbedTheme = 'dark-theme' | 'light-theme';

// Messages: Your App -> B2CORE
interface EmbedIframeReadyMessage {
  readonly type: 'embed-iframe-ready';
}

interface EmbedRequestJwtTokenMessage {
  readonly type: 'embed-request-jwt-token';
}

type EmbedOutboundMessage = EmbedIframeReadyMessage | EmbedRequestJwtTokenMessage;

// Messages: B2CORE -> Your App
interface EmbedThemeChangeMessage {
  readonly type: 'embed-theme-change';
  readonly theme: EmbedTheme;
}

interface EmbedLanguageChangeMessage {
  readonly type: 'embed-language-change';
  readonly lang: string; // ISO 639-1 code, e.g. "en", "de", "ar"
}

interface EmbedJwtTokenMessage {
  readonly type: 'embed-jwt-token';
  readonly token: string;
  readonly expiresAt: string; // ISO 8601
}

interface EmbedJwtTokenErrorMessage {
  readonly type: 'embed-jwt-token-error';
  readonly error: string;
}

interface EmbedLogoutMessage {
  readonly type: 'embed-logout';
}

type EmbedInboundMessage =
  | EmbedThemeChangeMessage
  | EmbedLanguageChangeMessage
  | EmbedJwtTokenMessage
  | EmbedJwtTokenErrorMessage
  | EmbedLogoutMessage;

Schritt 4 (optional). Validieren Sie das JWT-Token

Das von B2CORE ausgestellte JWT-Token kann anhand des vom B2CORE-API (Admin-Panel-Backend) bereitgestellten JSON Web Key Set (JWKS)-Endpunkts validiert werden. Dies ist in der Regel die API-/Admin-Domain und nicht die für Kunden bestimmte UI-Domain:

https://api.<your-domain>/.well-known/jwks.json

Verwenden Sie diesen Endpunkt, um die öffentlichen Schlüssel abzurufen, die zur Überprüfung der Token-Signatur erforderlich sind. Die meisten JWT-Bibliotheken unterstützen die JWKS-basierte Validierung standardmäßig.

Für eine manuelle Prüfung während der Entwicklung können Sie JWT-Token mit dem JWT-Decoder-Tool dekodieren und verifizieren.

Zuletzt aktualisiert am

Auf dieser Seite