Migration d'applications composites

Toutes les applications composites ne sont pas mises en œuvre de la même manière. Aidez-vous du contenu suivant, qui indique certaines des points à prendre en compte dans la procédure de migration d'applications composites. Avant de tenter de migrer des applications composites, assurez-vous d'avoir terminé les opérations suivantes :

• Vous avez déployé et configuré un client Qlik Cloud.

• Les utilisateurs peuvent s'authentifier via l'IdP, et les applications nécessaires ont été migrées vers les espaces partagés ou gérés appropriés, dans lesquels les utilisateurs sont titulaires au minimum des autorisations d'accès en lecture. Pour des informations sur les autorisations des espaces, voir Gestion des autorisations dans les espaces partagés et Gestion des autorisations dans les espaces gérés.

• Vous devez accéder au client via le rôle d'administrateur de clients (obligatoire pour créer une intégration Web).

Vous devez également savoir comment les applications composites Qlik Sense sont généralement mises en œuvre via JavaScript et HTML, qu'elles incorporent des objets uniquement avec IFrames ou avec les API de fonctionnalités Qlik.

À des fins de clarté, les nouvelles applications composites feront référence à celles dans Qlik Cloud et les anciennes à celles figurant dans Qlik Sense Client-Managed.

Intégrations Web

Vos nouvelles applications composites dans Qlik Cloud chargeront et incorporeront le contenu de votre client Qlik Cloud au lieu de Qlik Sense Client-Managed. Vous devez configurer une intégration Web dans Qlik Cloud afin de permettre l'identification de votre site Web d'applications composites (origine).

Les intégrations Web constituent un mécanisme de sécurité qui permet aux sites Web présentant un ID valide associé à une liste d'inclusions URL d'afficher des visualisations incorporées. Toute application Web qui interagit avec Qlik Cloud nécessite la configuration d'une intégration Web dans votre client.

Création d'une intégration Web dans Qlik Cloud

Pour créer une intégration Web, vous devez être un administrateur de clients dans Qlik Cloud.

Procédez comme suit :

1. Dans Console de gestion, accédez à la section Web et cliquez sur Créer un élément dans le coin supérieur droit.

2. Dans la boîte de dialogue, nommez l'intégration Web.

3. Saisissez l'adresse d'origine au format suivant : https://domain.com. Ensuite, cliquez sur Ajouter pour ajouter l'origine à la liste verte.

   Note InformationsVous pouvez ajouter plus d'une origine.
4. Cliquez sur Créer.

Une fois que vous avez créé l'intégration Web, vous recevrez un ID. Il s'agit de l'ID d'intégration Web Qlik de votre application composite, à savoir, un attribut ou paramètre obligatoire dans le code de la nouvelle application composite.

Pour plus d'informations sur la création d'intégrations Web, voir Gestion des intégrations Web.

Authentification

Les applications composites dans Qlik Sense Client-Managed gèrent généralement l'authentification via un proxy virtuel, sur lequel le mécanisme d'authentification est préconfiguré. Les options incluent, entre autres, Header, Ticket, SAML, JWT, OpenID Connect (OIDC) et Anonymous. Pour plus d'informations, consultez Solutions d'authentification (uniquement en anglais).

Dans votre ancienne application composite Qlik Sense Client-Managed, l'authentification est généralement gérée dans le code avant le chargement de toute ressource, y compris des bibliothèques et fichiers Qlik statiques nécessaires, via ce proxy virtuel.

Par exemple,

• Avec Ticket et JWT, un appel est généralement lancé vers le module d'authentification principal pour créer en toute sécurité un ticket Qlik ou un jeton JWT.

• Avec Header, un proxy inverse ou module sous-jacent définit l'en-tête approprié.

• Avec OIDC et SAML, il doit exister une redirection initiale vers le fournisseur d'identité correspondant qui déclenche le flux d'authentification pour finalement initier la session avec Qlik Sense, afin de permettre le chargement des ressources et le démarrage de l'incorporation de contenu.

Qlik Cloud n'utilise pas de proxy virtuel. À la place, il utilise une intégration Web que vous créez dans le client. Pour l'authentification, les deux mécanismes suivants sont disponibles : 

• Connexion interactive : ce mécanisme s'appuie sur l'IdP configuré utilisé par votre client pour l'accès courant. Il s'agit de l'Idp Qlik Account par défaut, ou de l'une des options disponibles telles que Okta, Auth0, ADFS, AzureAD, Salesforce, Generic et Keycloak.

• JSON Web Tokens (JWT) : ce mécanisme d'authentification s'appuie sur des jetons JWT signés généralement générés en toute sécurité par une service principal. Dans ce cas, il doit exister un fournisseur d'identité configuré dans votre client du type JWT.

Applications composites dans lesquelles des objets Qlik sont incorporés avec des API de fonctionnalités

Authentification via une connexion interactive

Mises à jour potentielles de code HTML

Comme avec votre application composite Qlik Sense Client-Managed, vous devez charger deux fichiers statiques Qlik dans la section <head> dans html (qlik-styles.css et require.js). Cependant, avec Qlik Cloud, ces fichiers sont directement accessibles sans aucune authentification requise.

Mises à jour potentielles de code JavaScript

Si votre application composite Qlik Sense Client-Managed utilise des API de fonctionnalités pour incorporer et interagir avec des objets dans Qlik Sense Client-Managed, examinez le code suivant, qui, dans cet exemple, incorpore plusieurs visualisations via la bibliothèque d'API de fonctionnalités Qlik.

Variable de configuration et baseUrl pour l'attribut require

Avec votre nouvelle application composite Qlik Cloud, la variable de configuration doit refléter les attributs host et webIntegrationId de votre client. En outre, étant donné l'absence de proxy virtuel, l'attribut prefix doit être seulement /. Vous pouvez définir un attribut identity de sorte que la session ne soit pas partagée et qu'elle soit utilisée uniquement pour le contexte de cette application composite. Le port doit être le port 443, qui implique que la valeur isSecure soit toujours définie sur true.

La configuration require doit contenir votre webIntegrationId, et baseUrl est plus simple, car les communications vers Qlik Cloud s'effectuent toujours via https sur le port 443.

Chargement des API de fonctionnalités

Avant de charger la bibliothèque d'API de fonctionnalités Qlik avec require (js/qlik), vérifiez si l'utilisateur est déjà connecté. Vous pouvez le faire, par exemple, en déclenchant un appel d'API REST pour le point de terminaison de métadonnées utilisateur existant. Si le statut de la réponse n'est pas 200, le code doit rediriger vers l'écran de connexion, injectant deux paramètres dans l'URL : returnto (l'URL de votre application composite en question) et qlik-web-integration-id.

Le code est exécuté comme suit :

• Vérifiez si l'utilisateur est déjà connecté en lançant une requête GET auprès du point de terminaison d'API REST /api/v1/users/me.

  • Si la réponse est négative (statut différent de 200), redirigez vers l'écran de connexion/login en ajoutant les paramètres returnto et qlik-web-integration-id.

  • Si la réponse est positive (statut égal à 200), chargez la bibliothèque d'API de fonctionnalités qlik/js avec require et continuez à utiliser cet ensemble d'API.

Le code final peut ressembler à celui de l'exemple suivant. Avec JavaScript, il n'existe pas une seule façon d'écrire le code parfait, c'est pourquoi il s'agit juste d'une option de code valide.

Authentification via JSON Web Token (JWT)

Configuration d'un fournisseur d'identité JWT

Un jeton JWT est le résultat du chiffrement de certaines métadonnées utilisateur de charge utile (telles que name, email, groups, subject) signé en toute sécurité via une clé privée de certificat. Toute personne avec la clé publique de certificat associée peut valider le jeton et lire informations utilisateur qu'il contient.

Pour que Qlik Cloud puisse valider vos jetons JWT signés, vous devez configurer un fournisseur d'identité dans votre client Qlik Cloud du type JWT. Une fois configuré, le client peut accepter et valider les requêtes d'API contenant un jeton JWT de porteur correctement signé.

Procédez comme suit :

1. Dans la Console de gestion, sélectionnez Fournisseur d'identité dans la section Configuration pour en créer un nouveau.

   

2. Collez la clé publique de certificat au format PEM dans la zone Certificat au-dessus.

   Si votre ancienne application composite utilise déjà JWT pour l'authentification auprès de Qlik Sense Client-Managed, il se peut que vous connaissiez déjà les clés publique et privée de certificat utilisées. Il se peut également que vous ayez déjà un service principal pour créer des jetons JWT signés. Si ce n'est pas le cas, voir Création de jetons signés pour l'autorisation JWT.

3. Vous pouvez éventuellement spécifier l'Émetteur et l'ID de clé ; dans les deux cas, ces valeurs vous seront fournies après la création.

   

Mises à jour potentielles du code du service principal de jeton JWT signé

Avec Qlik Sense Client-Managed, la charge utile nécessaire pour générer un jeton JWT nécessitait uniquement les requêtes ID utilisateur et Répertoire utilisateur, comme exigé par le proxy virtuel dans Qlik Sense pour l'authentification JWT. Avec Qlik Cloud, cette charge utile requiert davantage d'attributs de requête différents.

Vous devrez ajuster le code du service principal de génération de jeton JWT en fonction de la charge utile, en plus des options de signature nécessaires, pour refléter les conditions requises avec Qlik Cloud. Par exemple, les valeurs Émetteur et ID de clé du fournisseur d'identité JWT sont des options de signature obligatoires. Pour une description complète, voir Format JWT pour l’autorisation Qlik Sense.

Mises à jour potentielles de code HTML

Comme avec votre application composite Qlik Sense Client-Managed, vous devez charger deux fichiers statiques Qlik dans la section <head> dans html (qlik-styles.css et require.js). Cependant, avec Qlik Cloud, ces fichiers sont directement accessibles sans aucune authentification requise.

Mises à jour potentielles de code JavaScript

Le concept de code est similaire à celui de l'utilisation d'une connexion interactive. Cependant, dans ce cas, au lieu d'une redirection vers l'écran de connexion standard, vous devez initier une session JWT via le lancement d'une requête POST auprès du point de terminaison /login/jwt-session, en transmettant les en-têtes du jeton JWT du porteur et de l'ID d'intégration Web.

Procédez comme suit :

• Vérifiez si l'utilisateur est déjà connecté en lançant une requête auprès du point de terminaison d'API REST /api/v1/users/me.

  • Si la réponse est positive (statut égal à 200), chargez et utilisez la bibliothèque d'API de fonctionnalités qlik/js avec require.

  • Si la réponse est négative (statut différent de 200), déclenchez une requête POST pour initier la session JWT avec le jeton JWT signé donné.

    • Si la réponse est positive, chargez et utilisez la bibliothèque d'API de fonctionnalités qlik/js avec require.

  • Si elle est négative, il est probable que l'authentification JWT a échoué parce que le JWT n'est pas valide, a expiré ou n'est pas accepté.

Voici un exemple de code du processus décrit ci-dessus.

API de fonctionnalités et compatibilité dans Qlik Cloud

Les API de fonctionnalités sont une bibliothèque JavaScript qui vous permet d'interagir avec une collection de différentes API, par exemple, Root API, Visualization API, App API, Global API, Field API, Table API, Variable API, etc. Pour une liste complète, voir API de fonctionnalités.

Même si la compatibilité est quasiment complète entre Qlik Cloud et Qlik Sense Client-Managed lors de l'utilisation d'API de fonctionnalités pour votre application Web, il existe quelques différences subtiles ou méthodes non disponibles si vous utilisez cette bibliothèque JavaScript pour des sites Web avec des déploiements Qlik Cloud. Par exemple, Global API n'est pas disponible dans Qlik Cloud.

Pour plus de détails, voir Comparaison des API entre produits.

Applications composites dans lesquelles des objets Qlik sont incorporés avec IFrames

Outre la gestion de l'authentification telle que décrite dans Applications composites dans lesquelles des objets Qlik sont incorporés avec des API de fonctionnalités, vous devez savoir comment Qlik Cloud gère la Stratégie de sécurité de contenu (Content Security Policy ou CSP).

Stratégie de contenu de sécurité

La stratégie CSP dans des blocs Qlik Cloud permet d'accéder à des objets Qlik depuis d'autres domaines. Cela signifie que lors de l'incorporation d'objets Qlik via l'approche Single API IFrame, vous recevrez l'erreur de stratégie frame-ancestors ‘self’.

Voir Stratégie de contenu de sécurité pour savoir comment configurer CSP de sorte que votre application composite puisse utiliser IFrames pour incorporer des objets Qlik Cloud.

Applications composites via enigma.js

La bibliothèque enigma.js vous permet de communiquer avec Moteur associatif Qlik dans des environnements JavaScript.

Outre la gestion de l'authentification utilisateur et l'intégration Web requise, vous devez également tenir compte du concept Cross-site Request Forgery (CSRF) lorsque vous utilisez enigma.js sur Qlik.

Cross-Site Request Forgery (CSRF)

Qlik Cloud propose des contre-mesures pour vous protéger contre le Cross-Site Request Forgery (CSRF). Toute solution Web qui interagit avec Qlik Cloud doit fournir un jeton CSRF valide sur tous les appels autres que GET REST, y compris les connexions WebSocket.

Lors de l'utilisation de enigma.js dans votre application Web, dans votre code principal ou frontal, une connexion WebSocket est créée. Cela signifie qu'un jeton CRSF doit être inclus sous la forme d'un paramètre de la connexion WebSocket pour que la bibliothèque enigma.js puisse ouvrir une session sécurisée avec Qlik Cloud.

Une fois l'utilisateur connecté, un jeton CSRF valide peut être demandé auprès du point de terminaison /api/v1/csrf-token.

L'exemple de code suivant (avec un utilisateur connecté) d'enigma.js est utilisé dans le code frontal pour ouvrir une application et récupérer la disposition.

Pour voir un exemple de code complet, consultez les didacticiels suivants :

Didacticiel Création d'une simple application Web.

Gestion des feuilles dans iframes avec enigma.js