Guide de configuration des apps OAuth OpenConnector

OOMOL OpenConnector utilise votre propre app OAuth de fournisseur lorsqu’un fournisseur OAuth2 exige l’autorisation de l’utilisateur. Créez l’app dans la console développeur du fournisseur, copiez-y l’URL de callback exacte de votre runtime OpenConnector, puis enregistrez la configuration client de l’app dans OpenConnector.

Utilisez ce guide pour les fournisseurs OAuth2 tels que Gmail, Google Drive, Google Calendar, Slack, HubSpot, GitHub, Microsoft Outlook, Notion, Zoom, Zendesk, Jira, Dropbox et les autres fournisseurs OAuth affichés dans le catalogue OpenConnector.

Ce guide couvre la configuration des apps OAuth. Pour les fournisseurs qui utilisent un autre type d’authentification, utilisez les champs d’identifiants affichés sur leur page OpenConnector.

Éléments nécessaires

Un runtime OOMOL OpenConnector en cours d’exécution.
Un accès à la console web d’OpenConnector.
Le jeton d’administration si OOMOL_CONNECT_ADMIN_TOKEN est défini.
La permission de créer une app OAuth dans la console développeur ou administrateur du fournisseur.
Un compte de test dans l’espace de travail, le locataire, l’organisation ou le portail du fournisseur à connecter.

Si votre runtime est accessible via un domaine public, un tunnel ou une URL Cloudflare Worker, définissez OOMOL_CONNECT_ORIGIN avant de créer les apps OAuth des fournisseurs. L’URI de redirection est dérivée de cette origine.

OOMOL_CONNECT_ORIGIN="https://connect.example.com" \
OOMOL_CONNECT_ADMIN_TOKEN="replace-with-an-admin-token" \
OOMOL_CONNECT_ENCRYPTION_KEY="replace-with-a-long-random-secret" \
docker compose up --build

Étape 1 : définir l’URL de callback OpenConnector

Construisez l’URL de callback à partir de l’origine ouverte par les utilisateurs dans le navigateur :

<openconnector-origin>/oauth/callback

Avec le runtime local par défaut, utilisez :

http://localhost:3000/oauth/callback

Lorsque OOMOL_CONNECT_ORIGIN est défini sur une origine publique, l’URL de callback utilise cette origine :

https://connect.example.com/oauth/callback

Saisissez cette URL de callback exacte dans l’app OAuth du fournisseur. N’ajoutez pas de barre oblique finale, sauf si l’origine OpenConnector elle-même en possède une.

Étape 2 : créer l’app OAuth du fournisseur

Ouvrez la console développeur du fournisseur et créez une app OAuth, une intégration, une connected app, une app publique ou un enregistrement d’application. Les termes varient selon les fournisseurs, mais les champs requis sont généralement les mêmes.

Champ de l’app du fournisseur	Valeur à saisir
Nom de l’app	Un nom reconnaissable, comme `OpenConnector Local` ou le nom de votre outil interne.
URL de page d’accueil ou de site web	Votre produit, outil interne, dépôt ou URL runtime. Utilisez une valeur reconnaissable par vos utilisateurs et administrateurs.
URI de redirection, URL de callback ou URL de réponse	L’URL de callback OpenConnector exacte, par exemple `https://connect.example.com/oauth/callback`.
Scopes ou permissions	Les scopes requis par le fournisseur OpenConnector. Copiez-les depuis la page du fournisseur ou le guide de ses opérations.
Distribution, installation ou visibilité	Conservez l’app privée, réservée aux tests, interne ou non répertoriée lorsque le fournisseur le permet et que vous utilisez uniquement vos propres comptes.

De nombreux fournisseurs permettent d’autoriser votre propre compte, des utilisateurs de test, un espace de travail ou une organisation avant la publication sur une marketplace. Certains exigent néanmoins une vérification, une approbation administrateur ou une revue pour les scopes sensibles, l’utilisation en production, la distribution à de nombreux clients ou les espaces de travail gérés. L’écran d’autorisation et la console d’administration du fournisseur constituent la référence.

Étape 3 : copier la configuration client

Après avoir créé l’app du fournisseur, copiez les valeurs client requises par OpenConnector.

Valeur	Requise	Remarques
`clientId`	Oui	Généralement appelée Client ID, App ID, Application ID ou Consumer Key.
`clientSecret`	Généralement	Certains fournisseurs utilisent des flux de client public sans secret. Si OpenConnector marque le secret comme facultatif, laissez-le vide uniquement si le fournisseur le considère également comme facultatif.
Champs supplémentaires	Parfois	Certains fournisseurs exigent des données client OAuth supplémentaires, comme `tenant`, `subdomain`, `developerToken` ou des identifiants propres au compte. Utilisez une version de la console qui expose les champs nécessaires au fournisseur.

Ne placez pas les secrets des clients OAuth dans le code du navigateur, les dépôts publics, les captures d’écran, les tickets ou les prompts d’Agent.

Étape 4 : enregistrer le client OAuth dans OpenConnector

Utilisez la console web d’OpenConnector pour le parcours de configuration normal :

Ouvrez la console web d’OpenConnector, par exemple http://localhost:3000.
Ouvrez Providers et sélectionnez le fournisseur à connecter.
Choisissez Configure OAuth Client ou Edit OAuth Client.
Collez le Client ID et le Client Secret de l’app du fournisseur.
Choisissez Save OAuth Client.

Si le fournisseur exige des champs client supplémentaires, renseignez-les dans le même formulaire de client OAuth. Par exemple, les fournisseurs Microsoft nécessitent une valeur tenant. Si votre console n’affiche pas un champ exigé par le fournisseur, mettez OpenConnector à niveau vers une version prenant en charge son formulaire OAuth complet avant de poursuivre.

Après l’enregistrement, la page du fournisseur indique que le client OAuth est configuré et garde le secret client masqué.

Étape 5 : connecter un compte de test

Après avoir enregistré le client OAuth, restez sur la page du fournisseur et choisissez Connect pour lancer l’autorisation. Approuvez l’écran d’autorisation du fournisseur. Après la redirection vers OpenConnector, vérifiez que la page du fournisseur indique que le compte est connecté.

Étape 6 : tester une opération

Utilisez la page du fournisseur ou la liste des opérations de la console pour exécuter une opération de lecture à faible risque. Les détails de l’opération indiquent le schéma d’entrée, les scopes requis et l’identité de la connexion actuelle.

Utilisez des données de démonstration lors des tests d’opérations d’écriture.

Remarques sur les fournisseurs

Ces documents sont utiles pour créer les apps OAuth :

Famille de fournisseurs	Documentation officielle	Remarque courante
API Google	Using OAuth 2.0 for Web Server Applications	Utilisez un client OAuth de type application web. Ajoutez l’URI de redirection OpenConnector exacte aux URI autorisées. Les scopes sensibles ou restreints peuvent nécessiter une vérification Google avant une utilisation étendue en production.
Slack	Installing with OAuth	Ajoutez l’URI de redirection OpenConnector exacte aux URL de redirection de l’app. Utilisez une origine runtime publique ou un tunnel HTTPS si Slack refuse votre URL locale.
GitHub	Creating an OAuth app	Une app OAuth GitHub possède une seule URL de callback d’autorisation. Créez des apps distinctes si vous avez besoin d’URL différentes en local, staging et production.
Microsoft	Register an application with the Microsoft identity platform	Configurez une URI de redirection de plateforme Web et créez un secret client. Certains fournisseurs Microsoft d’OpenConnector exigent une valeur `tenant` comme `common`, `organizations` ou un ID de locataire.
HubSpot	Working with OAuth	Les scopes de la requête d’autorisation doivent correspondre à ceux de l’app. Les URL de redirection en production doivent utiliser HTTPS ; localhost peut utiliser HTTP pour les tests.
Notion	Authorization	Créez une connexion publique et ajoutez l’URI de redirection OpenConnector à la configuration OAuth. Consultez les règles actuelles de type d’app et de capacités Notion avant une utilisation hors de votre propre espace de travail.

Résolution des problèmes

Symptôme	Vérification
Le fournisseur indique `redirect_uri_mismatch`, une URI de redirection invalide ou une URL de callback invalide.	Vérifiez que l’app du fournisseur utilise `<openconnector-origin>/oauth/callback`. Le schéma, l’hôte, le port, le chemin et la barre oblique finale doivent correspondre à l’origine ouverte par les utilisateurs.
Le fournisseur refuse `http://localhost`.	Utilisez un fournisseur qui prend localhost en charge pour les tests, ou exposez le runtime via un tunnel HTTPS ou un domaine public et définissez `OOMOL_CONNECT_ORIGIN` sur cette origine avant de redémarrer OpenConnector.
Le fournisseur indique que l’app n’est pas vérifiée, approuvée ou autorisée dans l’espace de travail.	Vérifiez la distribution de l’app côté fournisseur, les utilisateurs de test, l’approbation des apps de l’espace de travail et les exigences de revue des scopes sensibles. La publication sur une marketplace est souvent distincte des tests privés, mais les règles varient.
L’autorisation réussit, mais une opération échoue faute de scopes.	Ajoutez les scopes requis par l’opération à l’app du fournisseur, enregistrez-la et reconnectez le compte pour accorder les nouveaux scopes.
OpenConnector indique `oauth_client_config_not_found`.	Enregistrez le client OAuth sur la même page de fournisseur où vous lancez Connect.
Le renouvellement du jeton échoue plus tard.	Vérifiez que le fournisseur a émis un refresh token. Certains fournisseurs exigent des paramètres d’accès hors ligne ou un nouveau consentement. Reconnectez le compte si aucun refresh token n’est disponible.
Le mauvais compte est utilisé pendant l’exécution.	Reconnectez-vous depuis un profil de navigateur connecté au compte voulu, puis sélectionnez la connexion correspondante dans la console avant de tester les opérations.

Liste de contrôle de sécurité

Définissez OOMOL_CONNECT_ENCRYPTION_KEY avant de stocker les secrets des clients OAuth ou les identifiants des comptes connectés.
Gardez OOMOL_CONNECT_ADMIN_TOKEN privé et utilisez des jetons runtime pour les appelants /v1 et /mcp.
Utilisez les scopes minimaux lorsque le fournisseur et l’ensemble des opérations OpenConnector le permettent.
Conservez des apps OAuth distinctes pour les environnements local, de staging et de production lorsque les règles de callback du fournisseur simplifient ainsi l’audit.
Supprimez les apps de fournisseurs inutilisées, les anciens secrets clients et les connexions OpenConnector obsolètes.