Migracja aplikacji typu mashup

Nie wszystkie aplikacje typu mashup są implementowane tak samo. Poniższą treść należy traktować jako przewodnik, w którym przedstawiono niektóre zagadnienia związane z migracją aplikacji typu mashup. Przed przystąpieniem do migracji aplikacji typu mashup należy wykonać następujące czynności:

• Wdrożyć i skonfigurować dzierżawę Qlik Cloud.

• Użytkownicy mogą uwierzytelniać się za pośrednictwem Dostawca tożsamości, a niezbędne aplikacje zostały przeniesione do odpowiednich przestrzeni udostępnionych lub zarządzanych, w których użytkownicy mają co najmniej uprawnienia Może wyświetlać. Informacje o uprawnieniach do przestrzeni zawiera temat Zarządzanie uprawnieniami w przestrzeniach udostępnionych oraz Zarządzanie uprawnieniami w przestrzeniach zarządzanych.

• Dostęp do dzierżawy w roli administratora dzierżawy (wymagany do utworzenia integracji internetowej).

Trzeba także wiedzieć, jak aplikacje Qlik Sense typu mashup są zwykle implementowane przy użyciu języków JavaScript i HTML, czy osadzają obiekty tylko w ramkach IFrame, czy też za pomocą interfejsów API Qlik Capability.

Dla jasności, nowe aplikacje typu mashup będą oznaczać te w Qlik Cloud, a stare aplikacje mashup to te istniejące w Qlik Sense zarządzany przez klienta.

Integracje sieciowe

Nowe aplikacje typu mashup w Qlik Cloud będą ładować i osadzać zawartość z Twojej dzierżawy Qlik Cloudzamiast z Qlik Sense zarządzany przez klienta. Musisz skonfigurować integrację sieciową w Qlik Cloud, aby mogła zidentyfikować Twoją witrynę aplikacji typu mashup (pochodzenie).

Integracje sieciowe to mechanizm bezpieczeństwa, który umożliwia renderowanie osadzonych wizualizacji witrynom prezentującym prawidłowy identyfikator powiązany z listą dołączania adresów URL. Każda aplikacja internetowa, która wchodzi w interakcje z Qlik Cloud, wymaga skonfigurowania integracji sieciowej w dzierżawie.

Tworzenie integracji sieciowej w Qlik Cloud

Aby utworzyć integrację sieciową, musisz być administratorem dzierżawy Qlik Cloud.

Wykonaj następujące czynności:

1. W funkcji Konsola zarządzania przejdź do sekcji Internet i kliknij przycisk Utwórz nowy w prawym górnym rogu.

2. W oknie dialogowym podaj nazwę integracji sieciowej.

3. Wpisz adres źródła w formacie: https://domain.com. Następnie kliknij przycisk Dodaj, aby dodać źródło do listy dozwolonych.

   InformacjaDodać można więcej niż jedno źródło.
4. Kliknij polecenie Utwórz.

Po utworzeniu integracji sieciowej otrzymasz identyfikator. Jest to identyfikator integracji sieciowej qlik dla Twojej aplikacji typu mashup, który jest wymaganym atrybutem lub parametrem w kodzie nowej aplikacji typu mashup.

Więcej informacji na temat tworzenia integracji internetowych zawiera temat Zarządzanie integracjami sieciowymi.

Uwierzytelnianie

Aplikacje typu mashup w Qlik Sense zarządzany przez klienta zwykle obsługują uwierzytelnianie za pośrednictwem wirtualnego serwera proxy, w którym mechanizm uwierzytelniania jest wstępnie skonfigurowany. Opcje obejmują między innymi Header, Ticket, SAML, JWT, OpenID Connect (OIDC) i Anonymous. Więcej informacji zawiera temat Rozwiązania do uwierzytelniania (tylko w języku angielskim).

W starej aplikacji typu mashup w Qlik Sense zarządzany przez klienta uwierzytelnianie jest zwykle obsługiwane w kodzie, zanim jakiekolwiek zasoby, w tym niezbędne pliki statyczne i biblioteki Qlik, zostaną załadowane przez ten wirtualny serwer proxy.

Na przykład:

• W przypadku opcji Ticket i JWT zwykle następuje wywołanie modułu uwierzytelniania zaplecza w celu bezpiecznego utworzenia biletu Qlik lub tokena JWT.

• W przypadku opcji Header odpowiedni nagłówek jest ustawiany przez jakiś bazowy moduł lub zwrotny serwer proxy.

• W przypadku opcji OIDC i SAML musi istnieć początkowe przekierowanie do odpowiedniego dostawcy tożsamości, które uruchamia przepływ uwierzytelniania, aby ostatecznie zainicjować sesję z Qlik Sense, aby umożliwić mu załadowanie zasobów i rozpoczęcie osadzania zawartości.

Qlik Cloud nie używa wirtualnego serwera proxy. Zamiast tego używa integracji sieciowej utworzonej w dzierżawie. Na potrzeby uwierzytelniania dostępne są dwa następujące mechanizmy: 

• Logowanie interaktywne — ten mechanizm opiera się na skonfigurowanym dostawcy tożsamości, którego dzierżawa używa do zwykłego uzyskiwania dostępu. Domyślnie jest to dostawca tożsamości Qlik Account lub dowolna z dostępnych opcji, takich jak Okta, Auth0, ADFS, AzureAD, Salesforce, Generic i Keycloak.

• JSON Web Tokens (JWT) — ten mechanizm uwierzytelniania opiera się na podpisanych tokenach JWT, które są zwykle bezpiecznie generowane przez usługę zaplecza. W takim przypadku w dzierżawie powinien być skonfigurowany dostawca tożsamości typu JWT.

Aplikacje typu mashup, w których obiekty Qlik są osadzone za pomocą interfejsów API Capability

Uwierzytelnianie przy użyciu logowania interaktywnego

Potencjalne aktualizacje kodu HTML

Podobnie jak w przypadku aplikacji mashup Qlik Sense zarządzany przez klienta należy załadować dwa pliki statyczne Qlik w sekcji <head> w kodzie html (qlik-styles.css i require.js). W przypadku Qlik Cloud pliki te są jednak dostępne bezpośrednio, bez konieczności uwierzytelniania.

Potencjalne aktualizacje kodu JavaScript

Jeśli Twoja aplikacja typu mashup w Qlik Sense zarządzany przez klienta używa interfejsów API Capability do osadzania obiektów oraz interakcji z nimi w Qlik Sense zarządzany przez klienta, przejrzyj poniższy kod, który w tym przykładzie osadza kilka wizualizacji przy użyciu biblioteki API Capability Qlik.

Zmienna konfiguracji i baseURL do require

W przypadku nowej aplikacji typu mashup Qlik Cloud zmienna konfiguracyjna musi odzwierciedlać hosta dzierżawy i webIntegrationId. Ponadto, ponieważ nie ma wirtualnego serwera proxy, prefiksem powinno być po prostu /. Możesz ustawić atrybut identity, aby sesja nie była udostępniana i była używana tylko w kontekście tej aplikacji typu mashup. Numerem portu musi być 443, co oznacza, że wartość isSecure jest zawsze prawdziwa.

Konfiguracja require powinna zawierać Twój webIntegrationId, a baseUrl jest prostszy, ponieważ komunikacja z Qlik Cloud zawsze odbywa się przez HTTPS na porcie 443.

Ładowanie interfejsów API Capability

Przed załadowaniem biblioteki API Capability Qlik przy użyciu require (js/qlik) sprawdź, czy użytkownik jest już zalogowany. Można to zrobić, na przykład, wyzwalając wywołanie interfejsu API REST dla punktu końcowego metadanych bieżącego użytkownika. Jeśli status odpowiedzi nie wynosi 200, kod musi przekierować do ekranu logowania, wstawiając dwa parametry do adresu URL: returnto (rzeczywisty adres URL Twojej aplikacji typu mashup) i qlik-web-integration-id.

Wykonanie kodu wygląda następująco:

• Sprawdź, czy użytkownik jest już zalogowany, używając żądania GET do punktu końcowego interfejsu API REST /api/v1/users/me.

  • Jeśli odpowiedź jest negatywna (ma stan inny niż 200), przekieruj do ekranu logowania /login, dodając parametry returnto i qlik-web-integration-id.

  • Jeśli odpowiedź jest pozytywna (stan to 200), załaduj bibliotekę API Capability qlik/js przy użyciu require i kontynuuj korzystanie z tego zestawu interfejsów API.

Ostateczny kod może wyglądać jak w poniższym przykładzie. W JavaScript nie ma jedynego sposobu na napisanie idealnego kodu, więc jest to tylko jedna z prawidłowych możliwości.

Uwierzytelnianie za pomocą JSON Web Token (JWT)

Konfiguracja dostawcy tożsamości JWT

Token JWT jest wynikiem szyfrowania niektórych metadanych użytkownika ładunku (takich jak imię i nazwisko, adres e-mail, grupy, podmiot), które są bezpiecznie podpisane za pomocą klucza prywatnego certyfikatu. Każdy, kto ma powiązany klucz publiczny certyfikatu, może zweryfikować poprawność tego tokena i odczytać zawarte w nim informacje o użytkowniku.

Aby umożliwić Qlik Cloud sprawdzanie poprawności podpisanych tokenów JWT, należy skonfigurować w dzierżawie Qlik Cloud dostawcę tożsamości typu JWT. Po skonfigurowaniu dzierżawa może akceptować i sprawdzać poprawność żądań interfejsu API, które zawierają prawidłowo podpisany token JWT okaziciela.

Wykonaj następujące czynności:

1. W Konsoli zarządzania wybierz pozycję Dostawca tożsamości z sekcji Konfiguracja, aby utworzyć nowego dostawcę.

   

2. Wklej klucz publiczny certyfikatu w formacie PEM w polu Certyfikat znajdującym się powyżej.

   Jeśli stara aplikacja typu mashup używa już JWT do uwierzytelniania w Qlik Sense zarządzany przez klienta, być może znasz już używane klucze prywatne i publiczne certyfikatu. Ponadto możesz już mieć usługę zaplecza do tworzenia podpisanych tokenów JWT. W przeciwnym razie zapoznaj się z tematem Tworzenie podpisanych tokenów do autoryzacji JWT.

3. Opcjonalnie możesz określić wystawcę i identyfikator klucza — w obu przypadkach otrzymasz te wartości po utworzeniu.

   

Podpisane potencjalne aktualizacje kodu usługi zaplecza tokena JWT

W Qlik Sense zarządzany przez klienta ładunek do wygenerowania tokenu JWT wymagał tylko oświadczeń identyfikatora użytkownika i katalogu użytkownika, zgodnie z wymaganiami wirtualnego serwera proxy w Qlik Sense dotyczącymi uwierzytelniania JWT. W Qlik Cloud ten ładunek wymaga więcej różnych atrybutów oświadczeń.

Należy dostosować kod usługi zaplecza generowania tokenów JWT dla ładunku, wraz z niezbędnymi opcjami podpisywania, zgodnie z wymaganiami obowiązującymi w przypadku Qlik Cloud. Na przykład wystawca i identyfikator klucza dostawcy tożsamości JWT są obowiązkowymi opcjami podpisywania. Pełny opis można znaleźć w temacie Format JWT do autoryzacji w Qlik Sense.

Potencjalne aktualizacje kodu HTML

Podobnie jak w przypadku aplikacji mashup Qlik Sense zarządzany przez klienta należy załadować dwa pliki statyczne Qlik w sekcji <head> w kodzie html (qlik-styles.css i require.js). W przypadku Qlik Cloud pliki te są jednak dostępne bezpośrednio, bez konieczności uwierzytelniania.

Potencjalne aktualizacje kodu JavaScript

Koncepcja kodu jest podobna jak w przypadku korzystania z logowania interaktywnego. Tutaj jednak, zamiast przekierowania do zwykłego ekranu logowania, należy zainicjować sesję JWT z żądaniem POST do punktu końcowego /login/jwt-session, przekazując nagłówki tokena JWT okaziciela oraz identyfikator integracji sieciowej.

Wykonaj następujące czynności:

• Sprawdź, czy użytkownik już się zalogował, przy użyciu żądania do punktu końcowego REST API /api/v1/users/me.

  • Jeżeli odpowiedź będzie pozytywna (status 200), załaduj i wykorzystaj bibliotekę API Capability qlik/js z require.

  • Jeśli odpowiedź jest negatywna (ma stan inny niż 200), wywołaj żądanie POST w celu zainicjowania sesji JWT z podanym podpisanym tokenem JWT.

    • Jeżeli odpowiedź będzie pozytywna, załaduj i wykorzystaj bibliotekę API Capability qlik/js z require.

  • Odpowiedź negatywna oznacza, że prawdopodobnie uwierzytelnienie JWT nie powiodło się, ponieważ token JWT jest nieważny, wygasł lub nie został zaakceptowany.

Poniżej przedstawiono przykład kodu procesu opisanego powyżej.

Interfejsy API Capability i kompatybilność w Qlik Cloud

API Capability biblioteka JavaScript, która umożliwia interakcję z kolekcją różnych interfejsów API, na przykład API Root, API Visualization, API App, API Global, API Field, API Table, API Variable itp. Pełną listę można znaleźć w temacie Funkcyjne interfejsy API.

Chociaż interfejsy API Capability są prawie całkowicie kompatybilne między Qlik Cloud a Qlik Sense zarządzany przez klienta podczas używania API Capability na potrzeby aplikacji internetowej, istnieje kilka subtelnych różnic lub niedostępnych metod, jeśli używasz tej biblioteki JavaScript do witryn internetowych z wdrożeniami Qlik Cloud. Na przykład interfejs API Global jest niedostępny w Qlik Cloud.

Więcej szczegółowych informacji zawiera temat Porównanie interfejsów API między produktami.

Aplikacje typu mashup, w których obiekty Qlik są osadzone przy użyciu IFrames

Oprócz obsługi uwierzytelniania zgodnie z opisem w temacie Aplikacje typu mashup, w których obiekty Qlik są osadzone za pomocą interfejsów API Capability musisz znać działanie zasad zabezpieczeń zawartości (CSP) w Qlik Cloud.

Zasady zabezpieczeń zawartości

Zasady CSP w Qlik Cloud blokują dostęp do obiektów Qlik z innych domen. Oznacza to, że podczas osadzania obiektów Qlik przy użyciu ramek IFrame w ramach API Single Integration pojawi się błąd zasad frame-ancestors ‘self’ .

Zobacz Zasady zabezpieczeń zawartości, aby się dowiedzieć, jak skonfigurować CSP, aplikacja typu mashup mogła używać ramek IFrame do osadzania obiektów Qlik Cloud.

Aplikacje typu mashup wykorzystujące bibliotekę enigma.js

Biblioteka enigma.js pomaga komunikować się z aparat asocjacyjny Qlik w środowiskach JavaScript.

Niezależnie od wymaganej integracji sieciowej i obsługi uwierzytelniania użytkowników, podczas korzystania z enigma.js w Qlik należy uwzględnić kwestię ataków Cross-site Request Forgery (CSRF).

Cross-Site Request Forgery (CSRF)

Qlik Cloud ma środki chroniące przed atakami Cross-Site Request Forgery (CSRF). Każde rozwiązanie internetowe, które wchodzi w interakcje z Qlik Cloud, musi udostępniać prawidłowy token CSRF dla wszystkich wywołań REST innych niż GET, w tym połączeń WebSocket.

Podczas korzystania z biblioteki enigma.js w aplikacji internetowej, w kodzie zaplecza lub frontonu, tworzone jest połączenie WebSocket. Oznacza to, że token CRSF musi być uwzględniony jako parametr połączenia WebSocket, aby biblioteka enigma.js mogła otworzyć bezpieczną sesję z Qlik Cloud.

Gdy użytkownik jest zalogowany, można wysłać żądanie prawidłowego tokenu CSRF do punktu końcowego /api/v1/csrf-token.

Poniższy przykład kodu (z zalogowanym użytkownikiem) biblioteki enigma.js jest używany w kodzie frontonu do otwarcia aplikacji i pobrania układu.

Aby zobaczyć pełny przykład kodu, skorzystaj z następujących kursów:

Kurs budowy prostej aplikacji internetowej.

Obsługa arkuszy w ramkach iframe za pomocą enigma.js