Aller au contenu principal

Guide étape par étape pour développer un connecteur social

La façon la plus rapide de commencer est de copier le code d’un connecteur officiel existant et de le modifier selon vos besoins. Prenons l’exemple du connecteur GitHub.

Étape 1 : Cloner un package de connecteur existant​

Dans un dossier source de connecteur, vous trouverez les fichiers suivants :

  • index.ts : Le fichier principal d’entrée du connecteur.
  • constant.ts : Les constantes utilisées dans le connecteur.
  • types.ts : Les types TypeScript utilisés dans le connecteur.
  • index.test.ts : Les cas de test pour le connecteur.
  • mock.ts : Les données simulées utilisées dans les cas de test du connecteur.

En plus de ces fichiers, vous devrez également fournir un fichier README.md pour décrire le connecteur, un logo.svg (éventuellement un logo-dark.svg pour une meilleure expérience en mode sombre), et un fichier package.json pour définir les informations du package npm.

Étape 2 : Modifier le fichier principal d’entrée (index.ts)​

Dans le fichier index.ts, vous trouverez la majorité de la logique du connecteur. Il y a généralement 4 fonctions à implémenter :

  • getAuthorizationUri : Génère l’URI d’autorisation pour la plateforme sociale tierce. Pour GitHub, cela serait : https://github.com/login/oauth/authorize?client_id={clientId}&redirect_uri={redirectUri}&state={state}. Consultez la documentation développeur de votre plateforme sociale cible pour obtenir l’URI correct.
  • authorizationCallbackHandler : Sécurise les valeurs des paramètres retournés dans l’URI de rappel d’autorisation, extrait le code d’autorisation et gère les erreurs potentielles.
  • getAccessToken : Échange le code d’autorisation contre un jeton d’accès.
  • getUserInfo : Récupère les informations utilisateur depuis la plateforme sociale tierce avec le jeton d’accès.

La plupart des autres logiques communes sont déjà prises en charge dans le kit de connecteur Logto, ce qui devrait faciliter votre travail.

Enfin, à la fin du fichier, il vous suffira d’exporter l’objet connecteur, en suivant la même structure de code que le connecteur GitHub.

const createGithubConnector: CreateConnector<SocialConnector> = async ({ getConfig }) => {
  return {
    metadata: defaultMetadata,
    type: ConnectorType.Social,
    configGuard: githubConfigGuard,
    getAuthorizationUri: getAuthorizationUri(getConfig),
    getUserInfo: getUserInfo(getConfig),
  };
};

Étape 3 : Tester le connecteur​

Test unitaire​

Commencez par écrire quelques cas de test unitaire et assurez-vous que les fonctionnalités de base fonctionnent comme prévu.

Test local​

  • Configurez Logto dans votre environnement local : Logto propose plusieurs façons de fonctionner en local, vous pouvez utiliser le CLI, Docker, ou même compiler à partir du code source. Consultez la documentation pour plus de détails.
  • Liez votre connecteur personnalisé à votre instance Logto : Utilisez le CLI pour créer un lien symbolique de votre connecteur vers l’instance Logto. Plus de détails. 
    cd logto
    npx @logto/cli connector link -p .
  • Après avoir lié le connecteur, vous devriez le voir dans le dossier <logto-root-path>/packages/core/connectors.
  • Redémarrez votre instance Logto, allez dans la Console d’administration Logto, vous devriez le voir dans la liste des connecteurs sociaux.
  • Configurez votre connecteur dans Console > Connexion & compte > Inscription et connexion > Connexion sociale. Et testez-le dans notre application de démonstration avec la fonctionnalité "Aperçu en direct".