Aller au contenu

Service externe — Personnalisé

Ajouter un service OAuth qui n'est pas fourni par Forra par défaut, ou utiliser votre propre application OAuth pour un service déjà supporté.

Quand utiliser cette procédure

  • Le service voulu n'est pas dans la liste des clients partagés Forra.
  • Vous voulez utiliser votre propre application OAuth pour un service supporté (contrôle des scopes, conformité, branding).
  • Vous intégrez une API interne ou un fournisseur de niche.

Prérequis

  • Une application OAuth 2.0 (Authorization Code) chez le fournisseur cible.
  • Le Client ID et le Client Secret de cette application.
  • Les URLs OAuth du fournisseur (authorize, token, api_base).
  • La liste des scopes nécessaires.
  • Le Redirect URI à déclarer côté fournisseur — voir plus bas.

1. Préparer le Redirect URI

Le Redirect URI à utiliser dans la configuration OAuth chez le fournisseur est de la forme :

https://{votre-domaine-scout}/api/external/callback/

Si vous n'êtes pas sûr du domaine canonique à utiliser, contacter l'équipe Forra.

2. Ajouter le service dans Forra

Dans l'Admin Locataire → Services externes → section Services OAuth, cliquer sur Ajouter un service. Renseigner :

Identification

  • Nom du service (name) : identifiant interne (ex. custom_crm).
  • Nom d'affichage (display_name) : nom visible par les utilisateurs (ex. CRM interne).
  • URL de l'icône (icon_url) : URL d'une image carrée affichée dans l'interface.

Endpoints OAuth

  • URL d'autorisation (authorize_url) : ex. https://votre-service.com/oauth/authorize
  • URL du jeton d'accès (access_token_url) : ex. https://votre-service.com/oauth/token
  • URL de base de l'API (api_base_url) : préfixe utilisé pour les appels API (ex. https://api.votre-service.com/v1/)
  • Paramètres de l'URL d'autorisation (authorize_url_params) : JSON optionnel pour des paramètres additionnels (ex. {"access_type": "offline", "prompt": "consent"})

Identifiants

  • ID client (client_id) : Client ID OAuth fourni par le service.
  • Secret client (client_secret) : Client Secret OAuth.

Scopes et instructions

  • Scopes (client_kwargs.scope) : liste séparée par des espaces des permissions à demander.
  • Usage de l'organisation (company_usage) : description courte de l'usage que fait votre organisation de ce service (ex. « Nous utilisons ce CRM pour gérer nos contacts clients en Amérique du Nord. »). Cette information est injectée dans le contexte des assistants pour aider le LLM à comprendre le contexte d'utilisation.
  • Documentation API (api_documentation_url) : URL d'un fichier Markdown décrivant l'API. Cette documentation est injectée dans le contexte des assistants utilisant ce service — c'est ce qui permet au LLM de savoir comment formuler les requêtes.

Visibilité

Définir qui peut connecter son compte à ce service. Voir Vue d'ensemble — Visibilité.

Enregistrer.

3. Tester

Demander à un utilisateur autorisé de se connecter au service depuis ses paramètres Forra. Vérifier qu'il est redirigé vers le fournisseur, puis revient bien dans Forra avec un état connecté.

Notes

  • La qualité d'utilisation du service par les assistants dépend largement de la qualité du fichier api_documentation_url. Un Markdown clair listant les endpoints, paramètres et exemples améliore significativement les résultats.
  • Pour héberger le fichier de documentation API, l'équipe Forra peut le publier sur files.scout.mirego.com au besoin.