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 :

authorization: Bearer <project-api-key>

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 :

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 :

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.

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 :

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.

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.

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 :

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 :

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 :

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 :

status=error
code=<connector-error-code>
message=<human-readable-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é.

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.