--- author: OOMOL author_url: https://oomol.com/fr/about/ title: Guide SaaS OOMOL Connector description: Permettez à un produit SaaS de connecter des comptes tiers pour ses utilisateurs finaux et d'exécuter des actions Connector depuis le backend. lang: fr canonical_url: https://oomol.com/fr/docs/connector-saas/ markdown_url: https://oomol.com/fr/docs/connector-saas.md --- # Guide SaaS OOMOL Connector OOMOL Connector SaaS est une couche de connexion de comptes pour les produits SaaS. Utilisez-la lorsque chaque utilisateur final doit connecter son propre compte Gmail, Slack, Notion ou un autre compte tiers, et que votre backend doit exécuter des actions Connector après autorisation. OOMOL Console gère les projets, les provider configs, les clés API et les enregistrements de connexion ; votre backend crée les liens d'autorisation, gère les callbacks, sélectionne les comptes et lance les appels d'action. Une intégration complète comporte deux parties : configurer un projet et un service dans OOMOL Console, puis faire créer par votre backend les liens d'autorisation, gérer les callbacks, sélectionner les comptes et exécuter les actions. Sujets principaux : - Les ressources qu'un administrateur prépare dans OOMOL Console. - Les IDs et secrets que votre backend doit stocker. - Ce que font votre frontend et votre backend lorsqu'un utilisateur final connecte un compte. - Comment sélectionner le compte connecté et exécuter une action. - Les pages Console, statuts, logs et vues d'utilisation utiles au dépannage. ## Modèle d'intégration Une intégration SaaS comporte une phase de configuration et une phase runtime. La phase de configuration se fait dans OOMOL Console. Elle prépare le projet, la provider config et la clé API backend, puis enregistre les IDs et secrets nécessaires au runtime. Les utilisateurs finaux ne participent pas à ces étapes. La phase runtime se fait dans le backend de votre produit. Elle représente votre projet SaaS lors de la création de liens de compte, de la lecture du statut d'une demande de connexion et de l'exécution d'actions. Les requêtes runtime incluent la clé API du projet : ```http authorization: Bearer ``` La clé API de projet reste sur votre backend. Les utilisateurs finaux utilisent seulement l'UI de votre produit ou ouvrent l'URL d'autorisation OAuth retournée par Connector. ## Données à stocker Une intégration typique stocke ces valeurs : | Valeur | Où la stocker | Pourquoi c'est important | | --- | --- | --- | | `projectId` | Configuration backend ou base de données | Identifie un projet SaaS. | | `providerConfigId` | Configuration backend ou base de données | Identifie une provider config dans le projet. Les appels runtime devraient la préférer. | | `projectApiKey` | Gestionnaire de secrets backend | Authentifie les appels runtime Connector. La clé en clair n'est retournée qu'une seule fois. | | `userId` | Base de données de votre produit | ID d'utilisateur final dans votre produit. Connector le stocke comme `externalUserId`. | | `connectedAccountId` ou `alias` | Base de données de votre produit | Sélectionne le compte connecté de l'utilisateur final lors de l'exécution des actions. | Si vos utilisateurs peuvent connecter plusieurs comptes Gmail, stockez le `connectedAccountId` ou l'`alias` de chaque compte afin que les appels runtime ne dépendent pas de la sélection par défaut du « dernier compte ». ## Étape 1 : créer un projet Un projet est la frontière d'isolation d'une intégration SaaS. Il isole les provider configs, clés API, comptes connectés, logs d'exécution et données d'utilisation. Dans OOMOL Console : ![Page Projects d'OOMOL Console avec une entrée Create project dans le panneau principal](/img/docs/connector-saas/en/project-list.webp) 1. Ouvrez **Projects** dans la barre latérale gauche. 2. Cliquez sur **Create project**. 3. Renseignez le nom du projet. 4. Après la création, ouvrez le projet et stockez l'ID de projet comme `PROJECT_ID`. ![Boîte de dialogue Create project avec le champ Project name et le bouton Create](/img/docs/connector-saas/en/create-project-dialog.webp) La page du projet contient des entrées comme **Provider configs**, **API Keys**, **Connected accounts**, **Execution logs** et **Usage**. Le reste de la configuration se fait dans ce projet. Le nom du projet apparaît sur la page d'entrée d'autorisation OAuth. En production, utilisez un nom de produit que les utilisateurs finaux reconnaissent afin que la cible d'autorisation soit claire. ## Étape 2 : créer une provider config Une provider config définit comment ce projet se connecte à un service Connector. Les requêtes runtime la transmettent comme `providerConfigId`. Pour Gmail OAuth : ![Page provider configs du projet avec le bouton Create provider config](/img/docs/connector-saas/en/service-configs-page.webp) 1. Ouvrez **Provider configs** dans la barre latérale du projet. 2. Cliquez sur **Create provider config**. 3. Sélectionnez ou remplissez les champs. 4. Cliquez sur **Create**. ![Boîte de dialogue Create provider config avec les champs service, auth type, config identifier, display name et client config source](/img/docs/connector-saas/en/create-service-config-dialog.webp) | Champ | Exemple Gmail | Notes | | --- | --- | --- | | Service | `Gmail` | Le service Connector à connecter. | | Auth type | `OAuth2` | Gmail utilise une autorisation OAuth2. | | Config slug | `gmail` | L'identifiant lisible que votre backend utilise pour cette config. Si le même projet a plusieurs configs pour un service, utilisez des noms comme `gmail-work` ou `gmail-personal`. | | Display name | `Gmail` | Le nom affiché aux utilisateurs finaux sur la page d'entrée d'autorisation. | | Client config source | `System Client` | Utilise le client OAuth fourni par OOMOL. | Après création, stockez l'ID de provider config comme `PROVIDER_CONFIG_ID`. Votre backend devrait le transmettre explicitement lors de la création de liens d'autorisation et de l'exécution des actions. Lorsque chaque projet SaaS utilise son propre client OAuth, changez **Client config source** vers un client personnalisé et fournissez les `clientId` et `clientSecret` correspondants. Avec un client OAuth personnalisé, configurez l'URL de callback Connector dans la console du fournisseur. OOMOL Console ou votre configuration de déploiement fournit cette URL ; les utilisateurs finaux n'en ont pas besoin. Pour un service par clé API, choisissez le type d'authentification par clé API correspondant. Lorsqu'un utilisateur final connecte un compte, votre backend envoie la clé API fournisseur de l'utilisateur à Connector pour stockage. ## Étape 3 : créer une clé API de projet La clé API de projet est réservée à votre backend. Ne l'envoyez pas aux navigateurs, clients mobiles ou appareils des utilisateurs finaux. Dans la page du projet : 1. Ouvrez **API Keys** depuis la barre latérale du projet. 2. Cliquez sur **Create API Key**. 3. Renseignez un nom de clé. Utilisez un nom qui facilite la rotation et le dépannage, par exemple `production server key` ou `staging server key`. 4. Cliquez sur **Create**. 5. Copiez la clé en clair depuis la boîte de dialogue à affichage unique et stockez-la comme `PROJECT_API_KEY`. ![Boîte de dialogue de clé à affichage unique avertissant que la clé complète ne sera plus affichée](/img/docs/connector-saas/en/api-key-once-dialog.webp) La clé en clair n'est retournée qu'une seule fois. Les listes suivantes n'affichent que le préfixe, l'heure de création, l'heure d'utilisation récente et des métadonnées similaires. Si la clé fuit, révoquez-la dans Console et créez-en une nouvelle. ## Étape 4 : permettre à l'utilisateur final de connecter un compte Passez maintenant au flux runtime du produit. Supposons que votre produit a un utilisateur avec l'ID `customer-1` et qu'il veut connecter Gmail. Votre backend crée un lien d'autorisation OAuth : ```bash CONNECTOR=https://connector.oomol.com PROJECT_API_KEY=oo_proj_... curl -sS -X POST "$CONNECTOR/v1/saas/connected-accounts/link" \ -H "content-type: application/json" \ -H "authorization: Bearer $PROJECT_API_KEY" \ -d '{ "providerConfigId": "pc-1", "userId": "customer-1", "alias": "work", "returnUri": "https://app.example/connector/callback" }' ``` La réponse contient `data.authorizationUrl`, une URL d'entrée d'autorisation possédée par Connector. Redirigez l'utilisateur final vers cette URL. Cette page affiche brièvement le titre du projet, l'icône du projet et le display name de la provider config, puis redirige vers la vraie page OAuth du fournisseur. Après l'autorisation de l'utilisateur, le fournisseur rappelle Connector, puis Connector redirige vers le `returnUri` fourni. En cas de succès, `returnUri` reçoit des paramètres de requête comme : ```text status=success service=gmail providerConfigId=pc-1 externalUserId=customer-1 connectedAccountId=ca-1 ``` Votre frontend peut envoyer `connectedAccountId` à votre backend pour stockage. Le backend peut aussi interroger le statut de la demande de connexion : ```bash curl -sS "$CONNECTOR/v1/saas/connection-requests/$REQUEST_ID" \ -H "authorization: Bearer $PROJECT_API_KEY" ``` Si l'utilisateur annule ou si le fournisseur retourne une erreur, `returnUri` reçoit : ```text status=error code= message= ``` `returnUri` doit utiliser `http` ou `https`. Les liens OAuth expirent par défaut après 10 minutes. ## Étape 5 : exécuter une action Une fois le compte connecté, le backend peut exécuter des actions avec le sélecteur de compte stocké. ```bash curl -sS -X POST "$CONNECTOR/v1/saas/actions/gmail.send_email" \ -H "content-type: application/json" \ -H "authorization: Bearer $PROJECT_API_KEY" \ -H "x-request-id: req-saas-action-1" \ -d '{ "providerConfigId": "pc-1", "userId": "customer-1", "connectedAccountId": "ca-1", "input": { "to": "someone@example.com", "subject": "Hello", "body": "Hello from My SaaS" } }' ``` Règles : - Transmettez exactement un seul élément parmi `providerConfigId` ou `service`. Les intégrations de production devraient préférer `providerConfigId`. - Transmettez au plus un seul élément parmi `connectedAccountId` ou `alias`. Les intégrations de production devraient en transmettre un explicitement. - Si aucun sélecteur de compte n'est présent, Connector choisit le dernier compte connecté actif sous le même `projectId + providerConfigId + userId`. - Le préfixe service de l'action ID doit correspondre au service de la provider config. Par exemple, `gmail.send_email` doit utiliser une provider config Gmail. La réponse de succès inclut `executionId`, `actionId` et la sortie d'action. Stockez `executionId` dans vos propres logs d'opération pour le support et le dépannage. ## Étape 6 : gérer les connexions utilisateur Les produits doivent généralement montrer aux utilisateurs quels comptes ils ont connectés. L'approche recommandée consiste à stocker `connectedAccountId`, `alias`, `service`, `providerConfigId` et votre propre `userId` dans la base de données du produit après un callback réussi, puis à afficher la liste des comptes à partir de ces données. Pour vérifier l'état côté Connector, utilisez **Connected accounts** dans OOMOL Console pour voir les comptes connectés du projet courant. Le champ `available` indique si le compte peut actuellement exécuter des actions. Il vaut `true` uniquement lorsque la provider config est active, le compte connecté est actif, l'app sous-jacente est active et un credential existe. Si votre produit permet aux utilisateurs de renommer des comptes, mettez d'abord à jour le display name dans la base de données de votre produit. Lorsqu'un administrateur doit vérifier l'état côté Connector, utilisez Console pour inspecter le compte correspondant. Lorsqu'un utilisateur déconnecte un compte, faites exécuter le flux de déconnexion par votre backend produit et mettez à jour la base de données de votre produit. Les administrateurs peuvent utiliser Console pour vérifier si le compte est encore disponible. La déconnexion conserve l'enregistrement du compte connecté mais supprime le credential sous-jacent. Les logs historiques peuvent encore référencer le compte ; les futures actions ne peuvent plus l'utiliser. ## Étape 7 : dépanner et exploiter Pour dépanner l'action d'un utilisateur, ouvrez **Execution logs** dans OOMOL Console. Les filtres courants incluent `providerConfigId`, `userId`, `appId`, `status=success|error` et `action`. Lors du dépannage, commencez par réduire la vue par service ou provider config. Si vos logs d'opération stockent `executionId`, utilisez-le pour relier une opération côté produit avec le log côté Connector. Pour l'exploitation, utilisez **Usage** afin de consulter les tendances d'utilisation quotidiennes et l'utilisation groupée par service. Les fenêtres courantes sont 7, 30 ou 90 jours. `days` ne prend en charge que `7`, `30` ou `90`. ## Ce que votre backend appelle au runtime Pour le flux OAuth Gmail de ce guide, le backend gère trois tâches : - Créer un lien d'autorisation et envoyer l'utilisateur vers l'entrée d'autorisation Connector. - Confirmer la demande de connexion après callback, puis stocker `connectedAccountId`. - Exécuter des actions avec le compte stocké lorsque l'utilisateur déclenche une fonctionnalité produit. Préférez OOMOL Console pour la configuration et les opérations comme la création de projets, la création de provider configs, la création de clés API de projet, la revue des comptes connectés, la lecture des logs d'exécution et le suivi de l'utilisation. ## Dépannage Quand une connexion de compte ou une exécution d'action échoue, vérifiez dans cet ordre : 1. Confirmez que votre backend utilise `PROJECT_API_KEY` pour le projet courant et que la clé n'est pas exposée aux navigateurs ou clients mobiles. 2. Confirmez que la requête utilise le `providerConfigId` de la provider config que vous avez créée. 3. Confirmez que le même utilisateur ne réutilise pas un `alias` existant. 4. Ouvrez **Connected accounts** dans Console et vérifiez si le compte est encore disponible. 5. Ouvrez **Execution logs** dans Console et filtrez par provider config, user ID ou `executionId`.