Sous-comptes délégués sans exposer les clés : modèle sécurisé pour les agences

Le problème : autonomie du client sans perte de contrôle

Une agence qui gère des livrables pour plusieurs clients a généralement besoin de deux choses qui semblent opposées : que chaque client puisse consulter, réviser, téléverser ou télécharger des fichiers avec une certaine autonomie, et que les opérations privilégiées restent sous le contrôle technique de l’agence. Le risque apparaît lorsque l’on tente de régler rapidement le problème en partageant des identifiants, en créant un utilisateur générique pour tous ou en laissant le navigateur invoquer des actions internes avec une clé API. Cette approche peut mélanger les espaces, briser la traçabilité et rendre très difficile la révocation d’accès sans affecter d’autres clients.

Le bon objectif n’est pas de masquer une interface, mais de séparer les responsabilités. Le client doit voir uniquement son contexte autorisé ; le backend de l’agence doit exécuter les actions avec privilèges ; et Apification Cloud doit appliquer les permissions, la visibilité, les groupes, les restrictions et les sessions intégrées limitées. Ce modèle permet de déléguer des sous-comptes sans exposer les clés API, en conservant les secrets côté serveur et en réduisant la dépendance aux opérations manuelles comme déplacer des fichiers, générer des liens ou vérifier un par un les travaux de transformation.

• Évitez de fournir des identifiants API au client ou de les inclure dans JavaScript.
• N’utilisez pas de compte partagé pour plusieurs clients si vous avez besoin d’un isolement opérationnel.
• Définissez dès le départ quelles actions relèvent de l’utilisateur et lesquelles relèvent du backend.
• Considérez chaque exposition de contenu comme une exception explicite sur des ressources privées par défaut.

Modèle mental : trois couches séparées

La première couche est l’interface intégrée. Apification permet d’intégrer Cloud au moyen d’un iframe, d’une configuration héritée et de thèmes visuels, afin qu’une agence ou un revendeur puisse proposer une expérience intégrée à son propre écosystème. Dans ce modèle, la session de l’iframe doit être construite avant son affichage : l’identité, la politique effective et la configuration visuelle sont résolues côté serveur à chaque lancement. La session intégrée peut être limitée au sous-compte, à l’utilisateur et aux ressources autorisées, ce qui évite que le navigateur décide lui-même de ce qu’il peut ouvrir.

La deuxième couche est le backend propre à l’agence. C’est là que résident les identifiants API, les secrets webhook et le matériel de signature, car Apification précise qu’ils doivent rester côté serveur et que le navigateur ne doit recevoir qu’un contexte limité ou temporaire. La troisième couche correspond aux contrôles de Cloud : permissions, utilisateurs, groupes, visibilité, restrictions, OTP, authentification externe lorsque cela s’applique et fenêtres de publication. La règle de conception est simple : l’interface guide l’utilisateur, le backend exécute les actions privilégiées et Cloud conserve la politique d’accès associée à la ressource.

• Iframe : expérience utilisateur et sélection dans un contexte limité.
• Backend : création de sessions signées, appels API et validation des règles du client.
• Cloud : fichiers, dossiers, services éditables, résultats, historique, permissions et visibilité.
• Webhooks : notifications d’événements avec signature, nouvelles tentatives, historique et statistiques.

Ce qu’Apification apporte à ce modèle

Apification rassemble les éléments nécessaires à une délégation contrôlée. Cloud conserve les fichiers, dossiers, services éditables et résultats générés dans un même espace de travail organisé et versionné. Les nouvelles ressources sont privées par défaut et ne sont publiées ou partagées que lorsque leur visibilité ou leurs destinataires sont configurés expressément. Elles peuvent aussi être partagées avec des utilisateurs ou des groupes sans modifier la visibilité publique, un point important lorsqu’une agence doit donner un accès interne à des réviseurs côté client sans rendre un livrable public.

Pour l’intégration, Apification propose une API REST serveur à serveur afin de gérer les ressources Cloud, les utilisateurs, la configuration et les travaux de transformation depuis le backend, ainsi qu’un contrat OpenAPI téléchargeable avec des schémas de requête et de réponse. La solution permet également d’intégrer Cloud et les services via iframe, API, webhooks et JavaScript, mais l’essentiel est de ne pas confondre « intégration avec JavaScript » et « secrets dans le navigateur ». Pour les opérations asynchrones, les webhooks signés avec nouvelles tentatives, historique et statistiques sont préférables au polling en production lorsque l’on attend des événements de transformation terminée ou échouée.

• Utilisez des clés API spécifiques et uniquement avec les scopes nécessaires.
• Appuyez-vous sur OpenAPI pour valider les contrats avant de programmer.
• Utilisez les webhooks en production afin de réduire les requêtes répétitives et d’améliorer la traçabilité.
• Réservez l’OTP aux interactions publiques ; utilisez les utilisateurs, groupes et règles de visibilité pour l’accès interne.

Architecture recommandée pour les sous-comptes délégués

Le flux recommandé commence dans le portail de l’agence. L’utilisateur du client s’authentifie dans le système de l’agence et demande à ouvrir son espace de fichiers ou une opération précise. Le backend valide à quel client il appartient, quel rôle il possède et quelles ressources il peut utiliser. Ce n’est qu’ensuite qu’il demande une session iframe signée et de courte durée depuis le backend de confiance, avec le contexte client isolé : sous-compte, utilisateur et ressources autorisées. Le navigateur reçoit cette session limitée, et non une clé API ni un secret réutilisable.

Lorsque le client a besoin d’une action privilégiée, comme créer un travail de transformation, consulter une ressource ou préparer un téléchargement transformé, le navigateur doit appeler le backend de l’agence, et non directement avec des identifiants permanents. Le backend applique les règles métier, invoque l’API REST d’Apification avec une authentification Bearer depuis le serveur et enregistre l’action. Si l’hôte et l’iframe se coordonnent au moyen de messages du navigateur, ces messages doivent être validés : le destinataire doit vérifier l’origine, l’intention et les données attendues, selon le principe général de validation des communications entre fenêtres.

• Étape 1 : authentifiez le client dans le portail de l’agence.
• Étape 2 : résolvez côté serveur l’identité, la politique effective et le thème visuel.
• Étape 3 : demandez une session iframe signée, limitée et de courte durée.
• Étape 4 : exécutez les appels REST uniquement depuis le backend avec une clé aux scopes minimaux.
• Étape 5 : enregistrez les événements et les réponses pour l’audit opérationnel.

Délégation par client : permissions, espaces et règles

La séparation ne doit pas dépendre uniquement du nom d’un dossier. Dans Apification, déplacer un élément Cloud modifie son organisation, pas son identité : ses propriétés et ses règles d’accès restent associées au même élément. C’est utile pour réorganiser les livrables sans perdre les contrôles, mais cela montre aussi pourquoi l’isolement doit reposer sur les permissions, les utilisateurs, les groupes, la visibilité et les ressources autorisées, et non sur des conventions fragiles comme « tout ce qui se trouve sous /client-a ». L’agence doit documenter la matrice d’accès par client et la réviser lorsque le contrat de service évolue.

Une matrice pratique distingue au moins cinq actions : téléverser ou intégrer des fichiers, transformer ou traiter du contenu, réviser des versions, télécharger des originaux ou des formats générés, et publier des liens ou des accès. Cloud permet de télécharger le fichier source ou de générer un format compatible depuis le flux de partage ; il est donc préférable de décider qui peut fournir les originaux et qui doit uniquement recevoir des dérivés. Si des services éditables sont utilisés, comme des documents bureautiques, l’édition d’images ou des éditeurs multimédias, la même logique s’applique : le client n’a pas besoin d’une permission universelle, mais du jeu minimal d’actions nécessaire à son cas.

• Définissez des groupes par client ou par rôle au sein du client.
• Séparez révision, transformation, téléchargement et publication comme des permissions distinctes dans votre conception.
• Évitez qu’un changement de dossier soit le seul mécanisme de contrôle.
• Maintenez une procédure de révocation lorsqu’un contact du client cesse de participer.

Opérations courantes et comment les automatiser

Dans une opération quotidienne, le client peut sélectionner des fichiers depuis l’iframe, réviser des livrables dans Cloud, télécharger un original ou demander une version transformée. De son côté, l’agence peut créer des travaux depuis le backend, appliquer les règles du client et utiliser l’historique des éléments pour consulter des versions antérieures ou restaurer du contenu lorsque c’est nécessaire. Cette approche réduit les e-mails isolés et évite que l’équipe interne doive servir d’intermédiaire pour chaque téléchargement ou révision de base.

Pour les processus asynchrones, concevez autour des événements. Si une transformation se termine ou échoue, un webhook signé peut avertir le backend de l’agence. Ce backend doit vérifier la signature avec le secret stocké côté serveur, dédupliquer les événements et mettre à jour son propre état. Apification prend en charge les écritures idempotentes au moyen d’une clé d’idempotence dans les opérations compatibles ; les actions susceptibles d’être répétées à cause de nouvelles tentatives, d’un double-clic ou de reconnexions doivent donc envoyer une clé stable. Vous évitez ainsi de créer des travaux en double ou de publier deux fois le même résultat.

• Utilisez les webhooks pour la clôture des travaux et les erreurs, pas seulement des requêtes périodiques.
• Vérifiez la signature avant de faire confiance au contenu de l’événement.
• Enregistrez les identifiants d’événements ou de résultats pour dédupliquer.
• Appliquez des clés d’idempotence aux écritures compatibles qui peuvent être répétées.
• Conservez un journal opérationnel indiquant qui a fait la demande, quelle ressource a été affectée et quel a été le résultat.

Erreurs fréquentes et modes de défaillance

L’erreur la plus grave consiste à placer des clés dans JavaScript. Même si une interface est privée ou protégée par une connexion, tout secret transmis au navigateur doit être considéré comme exposé. Une autre erreur courante est d’utiliser un seul utilisateur pour tous les clients : cela peut sembler pratique au départ, mais empêche d’attribuer les actions, complique la révocation des accès et augmente l’impact de toute erreur de configuration. Il est également dangereux de se fier uniquement aux noms de dossiers, car l’organisation visuelle ne remplace pas les règles d’accès associées aux ressources et aux utilisateurs.

En automatisation, les défaillances apparaissent souvent lorsque l’on ne vérifie pas les signatures webhook, que l’on traite deux fois le même événement ou que l’on suppose qu’une importation ponctuelle équivaut à une synchronisation continue. Si une livraison webhook est retentée et que votre backend n’est pas idempotent, vous pouvez dupliquer des travaux ou des notifications. Si vous ne testez pas avec des utilisateurs aux privilèges réduits, vous risquez de découvrir trop tard qu’un rôle peut télécharger des originaux alors qu’il devait seulement voir des éléments transformés. La défense consiste à tester les cas négatifs : mauvais utilisateur, ressource d’un autre client, session expirée, signature invalide et répétition d’événement.

• N’exposez pas de tokens Bearer, de secrets webhook ni de matériel de signature dans le frontend.
• Ne mélangez pas les clients sous une identité opérationnelle unique.
• Ne traitez pas de webhooks sans vérifier la signature et dédupliquer.
• Ne considérez pas une importation ponctuelle depuis des fournisseurs externes comme une synchronisation continue.
• N’accordez pas de scopes API étendus si l’intégration n’en nécessite qu’une partie.

Checklist d’implémentation avant la production

Avant d’ouvrir l’accès aux clients, préparez une checklist technique et une checklist opérationnelle. Côté technique, créez une clé API spécifique pour l’intégration et n’accordez que les scopes nécessaires pour le compte, Cloud, les transformations, les utilisateurs ou les webhooks. Stockez la clé et les secrets dans des variables ou un stockage serveur, jamais côté client. Implémentez une validation du client dans chaque endpoint interne : aucune requête du navigateur ne doit pouvoir indiquer librement un autre client, sous-compte ou ressource sans que le backend le vérifie avec sa propre autorisation.

Dans la checklist opérationnelle, documentez qui peut téléverser, transformer, réviser, télécharger, partager et révoquer. Créez des tests avec des utilisateurs aux privilèges réduits, validez les sessions iframe expirées et vérifiez que les ressources restent privées sauf publication explicite. Pour les webhooks, testez la signature invalide, l’événement dupliqué et la nouvelle tentative. Pour les écritures, appliquez l’idempotence lorsqu’elle est disponible. Enfin, définissez comment retirer l’accès à un client ou à un utilisateur sans affecter les autres : cette capacité de révocation est l’une des principales raisons de séparer les sous-comptes et de ne pas dépendre d’identifiants partagés.

• Matrice de permissions par client, rôle et action.
• Clés API spécifiques, scopes minimaux et secrets uniquement côté serveur.
• Session iframe signée, courte et créée depuis un backend de confiance.
• Validation du sous-compte, de l’utilisateur et de la ressource à chaque opération.
• Vérification des signatures webhook, déduplication et idempotence.
• Tests négatifs avec des rôles limités et des ressources d’autres clients.
• Plan documenté de révocation des utilisateurs, groupes et accès publiés.

Questions fréquentes