Migrieren von Mashups

Nicht alle Mashups werden auf die gleiche Weise implementiert. Betrachten Sie den folgenden Inhalt als Leitfaden, der einige Überlegungen für den Mashup-Migrationsprozess beschreibt. Die folgenden Schritte müssen abgeschlossen sein, bevor Sie Mashups migrieren können:

• Sie haben einen Qlik Cloud-Mandanten bereitgestellt und konfiguriert.

• Die Benutzer können sich über den IdP authentifizieren, und die erforderlichen Apps wurden in die entsprechenden freigegebenen und verwalteten Bereiche migriert, wo die Benutzer mindestens die Berechtigung „Kann anzeigen“ haben. Weitere Informationen zu Bereichsberechtigungen finden Sie unter Verwalten von Berechtigungen in freigegebenen Bereichen und Verwalten von Berechtigungen in verwalteten Bereichen.

• Greifen Sie mit der Mandantenadministrator-Rolle (für die Erstellung einer Webintegration erforderlich) auf den Mandanten zu.

Sie sollten auch damit vertraut sein, wie Qlik Sense-Mashups in der Regel mit JavaScript und HTML implementiert werden und wissen, ob sie Objekte nur mit IFrames oder mit den Qlik Capability APIs einbetten.

Der Begriff „neue Mashups“ bezieht sich auf Mashups in Qlik Cloud, während „alte Mashups“ diejenigen in Qlik Sense Client-Managed sind.

Webintegrationen

Ihre neuen Mashups in Qlik Cloud laden Inhalte anstelle von Qlik Sense Client-Managed aus Ihrem Qlik Cloud-Mandanten und betten sie ein. Sie müssen eine Webintegration in Qlik Cloud konfigurieren, damit Ihre Mashup-Website identifiziert werden kann (Ursprung).

Webintegrationen sind ein Sicherheitsmechanismus, mit dem Websites eine gültige ID verknüpft mit einer URL-Einschlussliste vorlegen können, um eingebettete Visualisierungen zu rendern. Für jede Webanwendung, die mit Qlik Cloud interagiert, muss eine Webintegration in Ihrem Mandanten konfiguriert werden.

Erstellen einer Webintegration in Qlik Cloud

Sie müssen ein Mandantenadministrator in Qlik Cloud sein, um eine Webintegration zu erstellen.

Gehen Sie folgendermaßen vor:

1. Gehen Sie in der Verwaltungskonsole zum Abschnitt Web und klicken Sie in der oberen rechten Ecke auf Neu erstellen.

2. Geben Sie der Webintegration im Dialogfeld einen Namen.

3. Geben Sie die Adresse der Herkunft in folgendem Format ein: https://domaene.com. Klicken Sie dann auf Hinzufügen, um die Herkunft zur Zulassungsliste hinzuzufügen.

   InformationshinweisSie können mehr als eine Herkunft hinzufügen.
4. Klicken Sie auf Create.

Nachdem Sie die Webintegration erstellt haben, erhalten Sie eine ID. Dies ist die Qlik-Webintegrations-ID für Ihr Mashup, ein erforderliches Attribut bzw. ein Parameter im Code des neuen Mashup.

Weitere Informationen zum Erstellen von Webintegrationen finden Sie unter Verwalten von Webintegrationen.

Authentifizierung

Mashups in Qlik Sense Client-Managed verarbeiten Authentifizierungen in der Regel über einen virtuellen Proxy, in dem der Authentifizierungsmechanismus vorkonfiguriert ist. Zu den Optionen zählen u. a. Header, Ticket, SAML, JWT, OpenID Connect ( OIDC) und Anonymous. Weitere Informationen finden Sie unter Authentifizierungslösungen (nur auf Englisch).

In Ihrem alten Qlik Sense Client-Managed-Mashup wird die Authentifizierung in der Regel im Code verarbeitet, bevor Ressourcen, einschließlich statischer Qlik-Dateien und -Bibliotheken, über diesen virtuellen Proxy geladen werden.

Beispielsweise

• Mit Ticket und JWT erfolgt üblicherweise ein Aufruf an das Backend-Authentifizierungsmodul, um auf sichere Weise ein Qlik-Ticket oder ein JWT-Token zu erstellen.

• Bei Header legt ein zugrunde liegendes Modul oder ein Reverse-Proxy den entsprechenden Header fest.

• Für OIDC und SAML muss eine anfängliche Umleitung an den entsprechenden Identitätsanbieter erfolgen, der den Authentifizierungsfluss auslöst, damit schließlich die Sitzung bei Qlik Sense initiiert werden kann, damit Ressourcen geladen und Inhalte eingebettet werden können.

Qlik Cloud verwendet keinen virtuellen Proxy. Stattdessen wird eine Webintegration verwendet, die Sie im Mandanten erstellen. Für die Authentifizierung stehen die folgenden beiden Mechanismen zur Verfügung: 

• Interaktive Anmeldung: Dieser Mechanismus stützt sich auf den konfigurierten IdP, den Ihr Mandant für den regulären Zugriff verwendet. Standardmäßig ist dies der Qlik Account IdP, es können aber auch andere verfügbare Optionen wie Okta, Auth0, ADFS, AzureAD, Salesforce, Generic und Keycloak ausgewählt werden.

• JSON Web Tokens (JWT): Dieser Authentifizierungsmechanismus stützt sich auf signierte JWT-Token, die in der Regel auf sichere Weise von einem Backend-Dienst generiert werden. In diesem Fall muss in Ihrem Mandanten ein konfigurierter Identitätsanbieter des Typs JWT vorhanden sein.

Mashups, in denen Qlik-Objekte mit Capability APIs eingebettet werden

Authentifizierung mit interaktiver Anmeldung

HTML – mögliche Codeaktualisierungen

Genau wie beim Qlik Sense Client-Managed Mashup müssen Sie zwei statische Qlik-Dateien in den Abschnitt <head> in HTML laden (qlik-styles.css und require.js). Es kann aber sein, dass in Qlik Cloud diese Dateien direkt zugänglich sind und keine Authentifizierung erforderlich ist.

JavaScript – mögliche Codeaktualisierungen

Wenn Ihr Qlik Sense Client-Managed-Mashup Capability APIs zum Einbetten und Interagieren mit Objekten in Qlik Sense Client-Managed nutzt, gehen Sie den folgenden Code durch, mit dem in diesem Beispiel mehrere Visualisierungen anhand der Capability API Qlik-Bibliothek eingebettet werden.

Konfigurationsvariable und baseUrl für Anforderung

Für das neue Qlik Cloud-Mashup muss die Konfigurationsvariable den host und die webIntegrationId Ihres Mandanten wiedergeben. Da kein virtueller Proxy vorhanden ist, muss zudem das prefix einfach / sein. Sie können ein identity-Attribut festlegen, damit die Sitzung nicht freigegeben und nur für den Kontext dieses Mashup verwendet wird. Der Port muss 443 sein, was bedeutet, dass isSecure immer wahr ist.

Die require -Konfiguration muss Ihre webIntegrationId enthalten, und baseUrl ist einfacher, da die Kommunikation mit Qlik Cloud immer über HTTPS an Port 443 erfolgt.

Laden von Capability APIs

Bevor Sie die Qlik Capability API-Bibliothek mit require (js/qlik) laden, prüfen Sie, ob der Benutzer bereits angemeldet ist. Dies kann z. B. geschehen, indem ein REST API-Aufruf für den Metadaten-Endpunkt es aktuellen Benutzers ausgelöst wird. Wenn der Antwortstatus nicht 200 ist, muss der Code zum Anmeldebildschirm umleiten, indem zwei Parameter in die URL eingefügt werden: returnto (zu Ihrer tatsächlichen Mashup-URL) und qlik-web-integration-id.

Die Codeausführung verläuft wie folgt:

• Prüfen, ob der Benutzer bereits angemeldet ist, indem eine GET-Anforderung an den REST API-Endpunkt /api/v1/users/me gesendet wird.

  • Wenn die Antwort negativ ist (Antwortstatus ist nicht 200), zum Anmeldebildschirm/login um, indem die Parameter „return to“ und „qlik-web-integration-id“ hinzugefügt werden.

  • Bei positiver Antwort (Antwortstatus ist 200) die qlik/js Capability APIs-Bibliothek mit require laden und mit der Verwendung dieses API-Satzes fortfahren.

Der fertige Code kann wie folgendes Beispiel aussehen: Mit JavaScript gibt es nicht einen eindeutigen Weg zum Schreiben des perfekten Codes, daher ist dies nur eine gültige Codeoption.

Authentifizierung über JSON Web Token (JWT)

Einen JWT-Identitätsanbieter konfigurieren

Ein JWT-Token ist das Ergebnis der Verschlüsselung bestimmter Nutzlast-Benutzermetadaten (z. B. Name, E-Mail, Gruppen, Antragsteller) nach sicherer Anmeldung mit einem privaten Schlüssel des Zertifikats. Jeder mit einem verknüpften öffentlichen Schlüssel des Zertifikats kann den Token validieren und die darin enthaltenen Benutzerinformationen lesen.

Damit Qlik Cloud Ihre signierten JWT-Token validieren kann, müssen Sie einen Identitätsanbieter des Typs JWT in Ihrem Qlik Cloud-Mandanten konfigurieren. Nach der Konfiguration kann der Mandant API-Anforderungen akzeptieren und validieren, die ein entsprechend signiertes Bearer-JWT-Token enthalten.

Gehen Sie folgendermaßen vor:

1. Wählen Sie in der Verwaltungskonsole Identitätsanbieter im Abschnitt Konfiguration aus, um einen neuen Identitätsanbieter zu erstellen.

   

2. Fügen Sie den öffentlichen Schlüssel des Zertifikats in PEM-Format in das Feld Zertifikat oben ein.

   Wenn Ihr altes Mashup bereits JWT für die Authentifizierung bei Qlik Sense Client-Managed verwendete, kennen Sie möglicherweise die verwendeten privaten und öffentlichen Schlüssel des Zertifikats. Außerdem haben Sie vielleicht schon einen Backend-Dienst zum Erstellen von signierten JWT-Token. Andernfalls finden Sie weitere Informationen unter Signierte Token für JWT-Autorisierung erstellen.

3. Optional können Sie den Aussteller und die Schlüssel-ID angeben. In jedem Fall werden diese Werte nach der Erstellung bereitgestellt.

   

Signierter JWT-Token – Backend-Dienst – mögliche Code-Aktualisierungen

In Qlik Sense Client-Managed erforderte die Nutzlast zum Generieren eines JWT-Tokens nur die Ansprüche Benutzer-ID und Benutzerverzeichnis, wie vom virtuellen Proxy in Qlik Sense für JWT-Authentifizierung verlangt. In Qlik Cloud erfordert diese Nutzlast mehr und andere Anspruchsattribute.

Sie müssen den Code des Backend-Diensts für die JWT-Token-Generierung für die Nutzlast anpassen, zusammen mit den entsprechenden Signieroptionen, um anzugeben, was für Qlik Cloud erforderlich ist. Beispielsweise sind der Aussteller und die Schlüssel-ID des JWT-Identitätsanbieters erforderliche Signieroptionen. Unter JWT-Format für Qlik Sense-Autorisierungen finden Sie eine vollständige Beschreibung.

HTML – mögliche Codeaktualisierungen

Genau wie beim Qlik Sense Client-Managed Mashup müssen Sie zwei statische Qlik-Dateien in den Abschnitt <head> in HTML laden (qlik-styles.css und require.js). Es kann aber sein, dass in Qlik Cloud diese Dateien direkt zugänglich sind und keine Authentifizierung erforderlich ist.

JavaScript – mögliche Codeaktualisierungen

Das Code-Konzept ähnelt dem der interaktiven Anmeldung. In diesem Fall muss jedoch wie folgt verfahren werden: Statt einer Umleitung zum regulären Anmeldebildschirm eine JWT-Sitzung mit einer POST-Anforderung am Endpunkt /login/jwt-session einleiten und die Header für den Bearer-JWT-Token und die Webintegrations-ID übergeben,

Gehen Sie folgendermaßen vor:

• Prüfen, ob der Benutzer bereits angemeldet ist, indem eine Anforderung an den REST API-Endpunkt /api/v1/users/me gesendet wird.

  • Bei positiver Antwort (Antwortstatus ist 200) die qlik/js Capability APIs-Bibliothek mit require laden und verwenden.

  • Bei negativer Antwort (Antwortstatus nicht 200) eine POST-Anforderung auslösen, um die JWT-Sitzung mit dem betreffenden signierten JWT-Token einzuleiten.

    • Bei positiver Antwort die qlik/js Capability APIs-Bibliothek mit require laden und verwenden.

  • Bei negativer Antwort ist wahrscheinlich die JWT-Authentifizierung fehlgeschlagen, weil der JWT ungültig oder abgelaufen ist oder nicht akzeptiert wurde.

Der folgende Code ist ein Beispiel des oben beschriebenen Prozesses.

Capability APIs und Kompatibilität in Qlik Cloud

Die Capability APIs sind eine JavaScript-Bibliothek, über die Sie mit einer Sammlung verschiedener APIs interagieren können, z. B. Root API, Visualization API, App API, Global API, Field API, Table API, Variable API und andere. Unter Capability APIs finden Sie eine vollständige Liste.

Obwohl fast vollständige Kompatibilität zwischen Qlik Cloud und Qlik Sense Client-Managed besteht, wenn Sie Capability APIs für Ihre Webanwendung verwenden, bestehen einige geringfügige Unterschiede oder nicht verfügbare Methoden, wenn Sie diese JavaScript-Bibliothek für Websites mit Qlik Cloud-Bereitstellungen verwenden. Beispielsweise ist Global API in Qlik Cloud nicht verfügbar.

Unter API-Vergleich zwischen Produkten finden Sie weitere Einzelheiten.

Mashups, in denen Qlik-Objekte mit IFrames eingebettet werden

Sie müssen nicht nur mit der Authentifizierung wie in Mashups, in denen Qlik-Objekte mit Capability APIs eingebettet werden beschrieben vertraut sein, sondern auch damit, wie Qlik Cloud die Content Security Policy (CSP) handhabt.

Content Security Policy

Die CSP-Richtlinie in Qlik Cloud blockiert den Zugriff auf Qlik-Objekte von anderen Domänen aus. Wenn also Qlik-Objekte mit dem Single API IFrame-Ansatz eingebettet werden, erhalten Sie den Richtlinienfehler frame-ancestors 'self'.

Unter Content Security Policy finden Sie Informationen zum Konfigurieren von CSP, damit Ihr Mashup IFrames zum Einbetten von Qlik Cloud-Objekten verwenden kann.

Mashups, die enigma.js verwenden

Die enigma.js-Bibliothek unterstützt Sie beim Kommunizieren mit der Qlik Associative Engine in JavaScript-Umgebungen.

Getrennt von der erforderlichen Webintegration und der Handhabung der Benutzerauthentifizierung müssen Sie auch das Konzept des Cross-Site Request Forgery (CSRF) beachten, wenn Sie enigma.js in Qlik verwenden.

Cross-Site Request Forgery (CSRF)

Qlik Cloud umfasst Gegenmaßnahmen zum Schutz vor Cross-Site Request Forgery (CSRF). Jede Weblösung, die mit Qlik Cloud interagiert, muss einen gültigen CSRF-Token bei allen Aufrufen außer GET REST-Aufrufen bereitstellen, auch bei WebSocket-Verbindungen.

Wenn Sie enigma.js in Ihrer Webanwendung entweder im Backend- oder im Frontend-Code verwenden, wird eine WebSocket-Verbindung erstellt. Das bedeutet, dass ein CRSF-Token als Parameter der WebSocket-Verbindung eingeschlossen werden muss, damit die enigma.js-Bibliothek eine sichere Sitzung mit Qlik Cloud öffnet.

Nachdem sich der Benutzer angemeldet hat, kann ein gültiger CSRF-Token für den Endpunkt /api/v1/csrf-token angefordert werden.

Das folgende Codebeispiel für enigma.js (mit einem angemeldeten Benutzer) wird im Frontend-Code verwendet, um eine App zu öffnen und das Layout abzurufen.

Ein vollständiges Codebeispiel finden Sie in den folgenden Tutorials:

Erstellen einer einfachen Web-App – Tutorial.

Umgang mit Arbeitsblättern in IFrames mit enigma.js