Intégrer Cloud embarqué sans exposer d’identifiants

Le problème : embarquer ne veut pas dire transmettre des identifiants

Intégrer un gestionnaire de fichiers avec iframe et API part souvent d’un besoin simple : afficher des fichiers, des dossiers, des transformations ou des téléchargements dans un produit existant. L’erreur courante consiste à supposer que, si l’interface s’affiche dans le navigateur, les clés qui permettent d’agir sur Cloud doivent aussi transiter par le navigateur. Ce mélange rompt la séparation de base entre expérience utilisateur et autorité d’exécution. L’iframe doit servir à présenter une session contrôlée ; l’API REST doit être utilisée depuis le serveur lorsqu’il faut gérer des ressources, des utilisateurs, de la configuration ou des travaux de transformation.

Apification propose trois modalités principales pour ce scénario : API REST, webhooks signés et Cloud embarqué. Cloud embarqué s’intègre au moyen d’une session contrôlée et personnalisée, avec des sessions iframe signées, des thèmes et des permissions effectives, ainsi qu’une communication JavaScript avec l’hôte. Cela ne revient pas à répliquer tout le stockage ni à exposer des chemins internes. Il ne faut pas non plus le confondre avec une synchronisation continue de sources externes : lorsque Google Drive, OneDrive ou Dropbox agissent comme sources, l’importation copie les fichiers sélectionnés vers le Cloud d’Apification.

• Ne placez pas de clés API dans le JavaScript client.
• Ne transformez pas un iframe en proxy sans règles métier.
• Ne traitez pas l’embarqué comme une copie totale du stockage externe.

Carte des responsabilités : frontend, backend et Cloud

Le frontend doit prendre en charge l’expérience : ouvrir la zone embarquée, réagir aux événements autorisés, afficher les états et demander les actions au backend. Un iframe, selon la définition générale de la plateforme web, est un contexte de navigation imbriqué qui intègre une autre page dans la page actuelle. Chaque iframe possède son propre document et sa propre navigation, et consomme de la mémoire ainsi que des ressources supplémentaires ; il convient donc de l’utiliser lorsqu’il apporte une expérience complète, et non comme mécanisme indiscriminé pour chaque opération minimale.

Le backend doit protéger les identifiants, appliquer les règles propres au produit et appeler l’API REST d’Apification de serveur à serveur. L’intégration REST prévoit des clés API avec scopes, des opérations d’écriture idempotentes et des travaux asynchrones de File Transformer. Apification Cloud, de son côté, maintient l’espace de travail organisé et versionné, les ressources partageables, les permissions, les utilisateurs, les groupes, les rôles et la visibilité qui contrôlent qui peut consulter ou modifier chaque élément.

• Frontend : interface, iframe, messages JavaScript limités et affichage d’état.
• Backend : authentification propre, autorisation, scopes, idempotence et appels REST.
• Apification Cloud : fichiers, services, permissions effectives, versions et résultats transformés.

Quand utiliser iframe, JavaScript, API REST ou OpenAPI

Utilisez Cloud embarqué lorsque vous voulez que l’utilisateur navigue dans une expérience de gestion de fichiers au sein de votre produit sans reconstruire toute l’interface. Apification permet des sessions iframe signées avec accès temporaire, et le serveur résout le thème ainsi que les permissions effectives avant d’ouvrir Cloud. Cela convient aux portails clients, aux tableaux de bord SaaS et aux back-offices où l’utilisateur doit voir une partie contrôlée du workspace, télécharger des originaux ou des fichiers transformés, ou travailler dans une expérience visuelle cohérente avec le produit hôte.

Utilisez l’API REST lorsque l’action a des conséquences métier ou doit s’exécuter avec les règles du serveur : créer un travail de transformation, gérer des ressources Cloud, appliquer une configuration ou coordonner des utilisateurs. Utilisez JavaScript uniquement pour une communication limitée entre la page hôte et l’iframe, pas pour exercer une autorité sensible. Utilisez le contrat OpenAPI 3.1 téléchargeable pour aligner les schémas de requête et de réponse, générer des clients internes ou valider des intégrations, en gardant à l’esprit que les identifiants avec scopes restent du côté du serveur.

• Iframe : meilleur pour une expérience Cloud complète et contrôlée.
• JavaScript : utile pour coordonner l’interface, pas pour les secrets.
• API REST : adaptée à l’automatisation, aux règles backend et aux travaux.
• OpenAPI : utile pour le contrat technique, les types, les tests et la revue des changements.

Modèle recommandé : le backend comme médiateur

Le modèle opérationnel le plus robuste commence par une requête de l’utilisateur adressée à votre application. Le backend valide la session interne, vérifie ce que cet utilisateur peut faire selon votre modèle métier et décide s’il faut ouvrir Cloud embarqué ou exécuter une action via l’API. Si Cloud est ouvert, le serveur prépare une session signée et temporaire, avec le thème et les permissions effectives résolus avant de livrer l’expérience au navigateur. Le client reçoit ce qui est nécessaire pour afficher l’iframe, pas un identifiant réutilisable.

Pour les opérations d’écriture ou de transformation, le backend utilise un identifiant avec scopes et n’accorde que les permissions de lecture et d’écriture nécessaires. Lorsque l’action peut se répéter à cause de nouvelles tentatives du navigateur ou de problèmes réseau, utilisez des opérations idempotentes pour éviter les doublons. Dans les flux lourds, comme les importations, transformations ou rendus, Apification peut traiter les travaux en arrière-plan. La séquence recommandée est claire : identifiant avec scopes, requête idempotente, travail asynchrone, événement signé et résultat authentifié.

• Validez l’utilisateur dans votre backend avant de créer une session embarquée.
• Faites correspondre les permissions métier aux permissions effectives de Cloud.
• Utilisez des scopes minimaux pour l’identifiant du serveur.
• Concevez les écritures pour tolérer les nouvelles tentatives sans dupliquer les actions.

Permissions, thèmes et restrictions sans élargir l’accès

La sécurité d’une intégration embarquée dépend moins de l’iframe lui-même que de la manière dont les permissions sont résolues avant son ouverture. Apification utilise des utilisateurs, groupes, rôles et règles de visibilité comme contrôles pour décider qui peut consulter ou modifier chaque élément. Dans une intégration, ces contrôles doivent s’aligner sur votre produit : si un client ne peut voir qu’un seul projet, la session embarquée ne doit pas lui permettre de naviguer vers les ressources d’un autre client, même s’il connaît un identifiant ou manipule des paramètres dans l’URL.

Le thème visuel doit lui aussi être résolu depuis le serveur au moment de préparer la session embarquée, car il fait partie de l’expérience contrôlée. Côté navigateur, considérez les attributs standard d’iframe comme une partie de la défense d’interface : allow définit une Permissions Policy pour les fonctions disponibles selon l’origine, et sandbox peut imposer des restrictions au contenu embarqué. La recommandation générale est de ne pas faire confiance au client comme source de permissions, et de faire attention aux combinaisons de sandbox qui annulent sa valeur de sécurité dans des scénarios de même origine.

• Vérifiez l’utilisateur, le groupe, le rôle et la visibilité avant d’ouvrir ou d’exécuter des actions.
• N’acceptez pas les permissions, le thème ou le périmètre final uniquement depuis les paramètres du client.
• Restreignez les fonctions de l’iframe à ce qui est nécessaire pour l’expérience.
• Vérifiez que les téléchargements d’originaux ou de fichiers transformés appartiennent au bon utilisateur.

Exemples de flux : sélecteur, transformation et téléchargement

Un flux de sélecteur embarqué peut fonctionner ainsi : l’utilisateur entre dans votre portail, sélectionne un projet et clique sur « ouvrir les fichiers ». Votre backend valide que cet utilisateur appartient au projet et demande une session embarquée avec les permissions effectives appropriées. Le frontend insère l’iframe et, au moyen d’une communication JavaScript limitée avec l’hôte, peut recevoir un signal de sélection ou de fermeture. L’action suivante ne doit pas se fonder aveuglément sur un ID envoyé par le navigateur ; le backend doit vérifier que l’élément sélectionné appartient bien au périmètre autorisé.

Un flux de transformation suit une autre logique. L’utilisateur demande à convertir, diviser, fusionner, optimiser ou traiter un document, une image, une vidéo, un audio ou une donnée au moyen d’une action de votre produit. Le backend valide le propriétaire et la permission, appelle l’API REST pour créer le travail asynchrone de File Transformer et enregistre un état interne comme « en cours ». Lorsque le résultat est disponible, l’utilisateur doit y accéder au moyen d’un résultat authentifié, et non par des chemins internes de stockage. Si le fichier original change, l’historique des éléments et des versions de Cloud aide à conserver une source organisée.

• Sélecteur : session embarquée, sélection limitée et validation ultérieure dans le backend.
• Transformation : permission, travail asynchrone, état visible et résultat authentifié.
• Téléchargement : original ou fichier transformé uniquement pour l’utilisateur ou le groupe autorisé.

Webhooks et actions asynchrones sans doublons

Les webhooks d’Apification permettent de réagir aux événements pertinents sans consulter en continu des ressources ou des travaux en arrière-plan. Ils incluent des payloads signés avec HMAC, un historique des livraisons, des nouvelles tentatives et des événements de transformation terminée. Pour bien les utiliser, vous avez besoin d’un endpoint HTTPS accessible et stable. Cet endpoint ne doit pas se contenter d’accepter n’importe quelle charge : il doit valider la signature, enregistrer l’événement reçu et le relier au travail ou à la ressource que votre backend a créé précédemment.

Comme il existe des nouvelles tentatives, votre récepteur doit être idempotent. En pratique, enregistrez une clé de livraison ou une référence d’événement et empêchez qu’une même transformation terminée déclenche deux fois la même action métier. Il est également utile de séparer l’état technique de l’état visible : « reçu », « traitement », « terminé » ou « échoué » dans vos enregistrements internes ; « votre fichier est en préparation » ou « la transformation n’a pas pu être terminée » dans l’interface. Ainsi, l’utilisateur comprend la progression sans voir de détails internes ni de chemins de stockage.

• Exigez un HTTPS stable pour l’endpoint de webhook.
• Validez HMAC avant de faire confiance au payload.
• Conservez l’historique des livraisons et le résultat du traitement.
• Rendez le gestionnaire idempotent face aux nouvelles tentatives.

Cas d’échec et checklist avant la production

Les échecs les plus dangereux apparaissent lorsque l’équipe essaie de simplifier l’intégration en contournant le backend. Une clé API dans JavaScript peut être extraite du client. Un proxy générique qui transmet n’importe quelle opération à l’API peut élargir les permissions sans le vouloir. Un endpoint qui fait confiance aux IDs envoyés par le navigateur rencontre des problèmes d’autorisation au niveau de l’objet : l’utilisateur modifie un identifiant et accède à une ressource qui ne lui appartient pas. La même logique s’applique aux propriétés : tout champ qui arrive du client ne doit pas être accepté comme modifiable.

Il existe aussi des échecs opérationnels. Si vous n’enregistrez pas les travaux en cours, les erreurs d’intégration ou les transformations échouées, l’utilisateur ne voit que du silence. Si vous ne limitez pas les actions lourdes, vous pouvez faciliter une consommation de ressources non prévue. Si vous ne distinguez pas l’embarqué de l’importation depuis des sources externes, vous pouvez promettre une synchronisation qui ne correspond pas. Avant la production, vérifiez que votre backend est la seule pièce qui possède des identifiants, que chaque action valide propriétaire et permission, et que les originaux comme les résultats transformés conservent une source unique de vérité dans Cloud.

• Identifiants : aucune clé API dans le navigateur.
• Autorisation : valider l’objet, le propriétaire, le groupe, le rôle et la visibilité dans le backend.
• Scopes : n’accorder que les lectures et écritures nécessaires.
• Proxy : n’autoriser que les opérations prévues par votre produit.
• Asynchronie : enregistrer les travaux, webhooks, nouvelles tentatives et erreurs visibles pour le support.
• Ressources : contrôler les actions lourdes et éviter les exécutions dupliquées.
• Messages utilisateur : afficher des états compréhensibles sans exposer de détails internes.

Questions fréquentes