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 pour répondre à vos besoins. Prenons le connecteur GitHub comme exemple.

Étape 1 : Cloner un package de connecteur existant​

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

  • index.ts : Le fichier d'entrée principal 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 utilisateur en mode sombre), et un fichier package.json pour définir les informations du package npm.

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

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

  • getAuthorizationUri : Générer l'URI d’Autorisation pour la plateforme sociale tierce. Pour GitHub, ce 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 : Protéger les valeurs des paramètres retournés dans l'URI de rappel d’Autorisation, extraire le code d’Autorisation et gérer les erreurs potentielles.
  • getAccessToken : Échanger le code d’Autorisation contre un jeton d’accès.
  • getUserInfo : Récupérer les informations utilisateur de la plateforme sociale tierce avec le jeton d’accès.

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

Enfin, à la fin du fichier, vous devrez simplement 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​

Tout d'abord, écrivez 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 fournit plusieurs façons de fonctionner localement, vous pouvez soit utiliser CLI, soit docker, ou même construire à partir du code source. Consultez les documentations 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 pouvoir le voir dans la liste des connecteurs sociaux.
  • Configurez votre connecteur dans Console > Expérience de connexion > Inscription et connexion > Connexion sociale. Et essayez-le dans notre application de démonstration avec la fonctionnalité "Aperçu en direct".