Insertion du tableau de bord et gestion des jetons d'accès
Intégration du tableau de bord dans K-Sup
Le tableau de bord est basé sur Apache Superset. Superset est hébergé par Kosmos. Pour pouvoir visualiser le tableau de bord, nous avons utilisé le
package NPM @superset-ui/embedded-sdk. Il se charge de gérer lui-même l'intégration du tableau de bord dans la page, via
une iframe. Il permet également de renouveler automatiquement le jeton d'accès qui permet de visualiser le tableau de bord.
Lorsqu'un utilisateur accède à la page de visualisation des statistiques, du JavaScript se lance pour faire appel à une JSP renvoyant seulement le token d'accès en JSON. Ce token d'accès est soit généré en appelant l'API de Superset, soit donné directement dans les propriétés de l'application. Le tableau de bord est ensuite affichée dans l'iframe grâce au package qui se charge de lui fournir les données dont elle a besoin.
Configuration nécessaire pour le tableau de bord
Afin de pouvoir voir le tableau de bord, il faut renseigner la propriété dashboard.guestToken (jeton généré par Kosmos, voir ci-dessous). Par défaut, le profil Webmaster a la
permission de voir le tableau de bord. Pour les autres profils, il faut leur accorder l'accès (permission à donner dans la gestion des rôles).
Gestion de l'accès au tableau de bord
Afin de visualiser le tableau de bord, il faut soit :
- Générer un jeton d'accès (guest_token) grâce à un utilisateur Superset qui a les droits nécessaires
- Donner un jeton valide au package embedded-sdk
Remarque : Nous utilisons un seul tableau de bord et un seul serveur Apache Superset pour tous les clients. Ils accèdent au même tableau de bord, mais avec des restrictions d'accès différentes (ils ne voient que les données de leur établissement). Or, seul un utilisateur peut être désigné pour générer les jetons d'accès dans Superset. On ne peut donc pas créer un utilisateur par client et restreindre l'accès aux données directement depuis Superset. K-Sup étant open source, on ne peut pas non plus définir les restrictions d'accès dans le projet, car elles seraient modifiables et les établissements pourraient changer le code pour accéder à d'autres données (toutes les données ou celles d'autres établissements). Le choix fait pour l'instant est que Kosmos génère un jeton d'accès avec des droits qui limitent aux données d'un seul établissement. Il y a ainsi un token à générer par client.
Les properties mentionnées sont dans le fichier src/main/resources/core-statistics.properties.
Avec un jeton d'accès entré manuellement
Si on choisit de saisir manuellement un jeton, il aura été généré au préalable par Kosmos et aura une durée de vie longue (plusieurs mois, voire plusieurs années). Il est renseigné
par la propriété dashboard.guestToken.
Les jetons prennent en compte des restrictions d'accès aux données (pour que chaque établissement ne voie que ses données).
Le diagramme suivant détaille ensuite le déroulement de l'affichage du tableau de bord si un jeton est entré manuellement. Le participant "Embed Superset (client)" désigne le package NPM embedded-sdk utilisé automatiquement par le client.
Les tokens sont générés via un script interne à Kosmos dont voici le diagramme de séquence.
Voici la liste des variables les propriétés qui leur correspondent ainsi qu'une valeur d'exemple :
| Nom de la variable dans le diagramme | Description | Propriété correspondante | Valeur d'exemple |
|---|---|---|---|
| idDashboard | Identifiant du tableau de bord qu'on souhaite visualiser | dashboard.id | 4adbc771-5b67-48d7-a656-8447cd4db8f0 |
| RLS | Restrictions d'accès aux données du tableau de bord | organisation='Kosmos' | |
| hostUrl | URL de l'hébergeur d'Apache Superset | dashboard.provider.hostname | https://ksup.analytics.skolengo.com |
| apiLoginPath | Path de l'API d'Apache Superset, qui renvoie un jeton d'accès et un refresh token | dashboard.provider.api.login | "/api/v1/security/login" |
| apiGuestTokenPath | Path de l'API d'Apache Superset pour obtenir le guest_token (jeton permettant de visualiser le tableau de bord) | dashboard.provider.api.guest_token | "/api/v1/security/guest_token" |
| username | Nom d'utilisateur pour le profil ayant le droit de générer un guest token | dashboard.provider.username | |
| password | Mot de passe de l'utilisateur pour le profil ayant le droit de générer un guest token | dashboard.provider.password | |
| provider | Provider du tableau de bord | dashboard.provider.provider | db |
| refresh | Vrai si on souhaite obtenir un refresh token lors de la connexion à l'API, faux sinon | dashboard.provider.refresh | true |
| TYPE_DASHBOARD | Type de ressource demandée à Superset, variable statique de com/kosmos/statistics/api/superset/model/RessourceForGuestToken.java | TYPE_DASHBOARD | dashboard |
Avec un jeton d'accès généré puis renouvelé
Pour pouvoir générer un jeton d'accès, il faut disposer du nom d'utilisateur et mot de passe du compte qui a les droits pour générer ce jeton. On peut les renseigner via les
propriétés dashboard.provider.username et dashboard.provider.password.
Le package intégrant le tableau de bord se chargera ensuite de faire les appels nécessaires à Superset pour obtenir le jeton. Il sera renouvelé toutes les 5 minutes et peut intégrer des restrictions d'accès aux données (pour que chaque établissement n'ait accès qu'à ses données).
On doit tout d'abord se connecter à l'API de Superset en précisant l'utilisateur, le provider (db ou ldap) ainsi qu'un booléen indiquant si on souhaite obtenir un token de rafraîchissement ou non. Une fois connecté à l'API, on peut demander le guest_token, en précisant le token d'accès (utilisé pour se connecter à l'API), le nom d'utilisateur, le type de ressource à laquelle on souhaite accéder, l'identifiant du tableau de bord auquel on souhaite accéder puis des restrictions d'accès aux données (en choisissant un établissement par exemple).
Le diagramme suivant explique les appels faits par le
processus /src/main/java/com/kosmos/statistics/processus/VisualiserStatistiques.java si un
utilisateur générant un token est renseigné.
Les variables utilisées sont les mêmes que celles désignées dans le tableau ci-dessus à l'exception de tokenUrl. Cette variable désigne l'URL de la JSP qui contient le guestToken.
En effet, les appels montrés sont déclenchés par un fetch d'une page contenant seulement un guest token JSON, effectué par le JavaScript de ka JSP de visualisation des
statistiques.