Migration d’applications OAuth vers des applications GitHub

Découvrez les avantages de la migration de votre OAuth app vers un GitHub App, et découvrez comment migrer votre OAuth app.

Dans cet article

Avantages de la migration vers OAuth appsGitHub Apps

GitHub Apps sont la méthode recommandée pour s’intégrer à GitHub. GitHub Apps offrent de nombreux avantages par rapport à OAuth apps, notamment :

  • Fonctionnalités de sécurité améliorées, telles que des autorisations fines, le choix de l'accès au référentiel et des jetons à durée de vie courte
  • La capacité d'agir indépendamment ou au nom d'un utilisateur
  • Limites de taux modulables
  • Webhooks intégrés

Pour plus d’informations, consultez « À propos de la création d’applications GitHub ».

Conversion d’un OAuth app en un GitHub App

Les étapes suivantes fournissent une vue d’ensemble de la migration d’un OAuth app vers un GitHub App. Les étapes spécifiques dépendent de votre application.

1. Passez en revue votre OAuth app

Refamiliarisez-vous avec le code de votre OAuth app. Les requêtes API que votre OAuth app effectue vous aideront à déterminer les autorisations à sélectionner pour votre GitHub App.

En outre, il existe quelques points de terminaison d’API REST qui ne sont pas disponibles pour OAuth apps. Vérifiez que tous les points de terminaison REST que vous utilisez sont disponibles pour GitHub Apps en consultant Points de terminaison disponibles pour les jetons d’accès d’installation d’application GitHub.

2. Inscrire un GitHub App

Enregistrer un nouveau GitHub App. Pour plus d’informations, consultez « Inscription d’une application GitHub ».

Par rapport à un OAuth app, vous avez davantage de contrôle sur les paramètres de GitHub App. Voici quelques ajouts clés :

  • Contrairement à un OAuth app, qui agit toujours au nom d’un utilisateur, vous pouvez faire en sorte que votre GitHub App effectue des actions en son nom propre ou au nom d’un utilisateur. Si vous ne souhaitez pas que votre nouveau GitHub App effectue des actions pour le compte d’un utilisateur, vous pouvez ignorer les paramètres « Identification et autorisation des utilisateurs ». Pour plus d’informations, consultez « À propos de l’authentification avec une application GitHub ».

  • Vous pouvez utiliser des webhooks pour notifier votre GitHub App lorsque des événements spécifiques se produisent. Contrairement aux webhooks pour OAuth apps, que vous devez configurer via l’API pour chaque référentiel ou organisation, les webhooks sont intégrés GitHub Apps. Lorsque vous enregistrez votre GitHub App, vous pouvez sélectionner les événements de webhook que vous souhaitez recevoir. En outre, si votre OAuth app recourt actuellement à l’interrogation périodique pour vérifier si un événement s’est produit, envisagez plutôt de vous abonner à des webhooks afin d’aider votre GitHub App à respecter la limite de débit. Pour plus d’informations, consultez « Utilisation de webhooks avec GitHub Apps ».

  • À l’aide d’un OAuth app, vous demandez des périmètres lorsqu’un utilisateur autorise votre application. Avec un GitHub App, vous spécifiez des autorisations dans les paramètres de l’application. Ces autorisations sont plus affinées que les étendues et vous permettent de sélectionner uniquement les autorisations dont votre application a besoin. En outre, ces autorisations sont mappées aux points de terminaison d’API REST et aux événements webhook. Vous pouvez donc facilement déterminer les autorisations dont vous GitHub App avez besoin pour accéder à un point de terminaison d’API REST spécifique ou s’abonner à un webhook spécifique. Actuellement, les autorisations ne sont pas documentées pour les demandes GraphQL. Pour plus d’informations, consultez « Choix des autorisations pour une application GitHub ».

3. Modifier le code de votre application

Une fois que vous avez inscrit un GitHub App, adaptez le code de votre ancien OAuth app pour travailler avec votre nouveau GitHub App.

Mettre à jour l’authentification

Vous devez mettre à jour le code de votre application pour gérer l’authentification d’API pour votre GitHub App. Un GitHub App peut s’authentifier de trois façons :

Si vous utilisez GitHubla bibliothèque de Octokit.js officielle, vous pouvez utiliser l’objet intégré App pour vous authentifier. Pour obtenir des exemples, consultez « Écriture de scripts avec l’API REST et JavaScript » et « Création d’une application GitHub qui répond aux événements de webhook ».

Passer en revue les limites de débit

Passez en revue les différences dans les limites de taux entre OAuth apps et GitHub Apps. GitHub Apps utilisez des règles glissantes pour les limites de débit, qui peuvent augmenter en fonction du nombre de référentiels et du nombre d’utilisateurs de l’organisation. Pour plus d’informations, consultez « Limites de débit pour les applications GitHub ».

Si possible, envisagez d’utiliser des demandes conditionnelles et de vous abonner à des webhooks plutôt que d’utiliser l’interrogation, afin de vous aider à rester dans les limites de débit. Pour plus d’informations sur les demandes conditionnelles, consultez « Meilleures pratiques pour utiliser l'API REST ». Pour plus d’informations sur l’utilisation de webhooks avec votre GitHub App, consultez Utilisation de webhooks avec GitHub Apps et Création d’une application GitHub qui répond aux événements de webhook.

Tester votre code

Testez votre nouveau GitHub App pour vous assurer que votre code fonctionne comme prévu.

4. Faites connaître votre nouveau GitHub App

Si vous souhaitez que d’autres comptes puissent utiliser votre nouveau GitHub Appcompte, assurez-vous que votre application est publique. Si vous souhaitez rendre votre application GitHub App plus visible, répertoriez votre application dans GitHub Marketplace. Pour plus d’informations, consultez À propos de GitHub Marketplace pour les applications et Création d’une application GitHub publique ou privée.

5. Demander à vos utilisateurs de procéder à la migration

Une fois que votre nouveau GitHub App est prêt, demandez aux utilisateurs de votre ancien OAuth app de migrer vers votre nouveau GitHub App. Il n’existe pas de moyen d’effectuer une migration automatique de vos utilisateurs. Chaque utilisateur doit installer et/ou autoriser GitHub App de son côté.

En tant que propriétaire de l’application, vous devez inclure des appels à l’action pour encourager vos utilisateurs à installer/autoriser le nouveau GitHub App et révoquer l’autorisation pour l’ancien OAuth app. Vous devez également mettre à jour la documentation ou les éléments de l’interface utilisateur.

Inviter les utilisateurs à installer votre GitHub App

Si vous souhaitez que votre GitHub App effectue des requêtes API en son propre nom ou accède aux ressources de l’organisation ou du dépôt, l’utilisateur doit installer votre GitHub App. Lorsqu’un utilisateur installe un GitHub App sur son compte ou dans son organisation, il choisit les référentiels auxquels l’application peut accéder et accorde à l’application les autorisations d’organisation et de référentiel qu’elle a demandées.

Pour aider vos utilisateurs à installer votre GitHub App, vous pouvez ajouter sur la page Web de votre application un lien sur lequel les utilisateurs peuvent cliquer pour installer le GitHub App. Le format de l’URL d’installation est https://github.com/apps/YOUR_APP_NAME/installations/new. Remplacez YOUR_APP_NAME par la version slug du nom de votre GitHub App, que vous trouverez dans le champ « Lien public » sur la page des paramètres de votre GitHub App.

Pour présélectionner les dépôts auxquels votre OAuth app avait accès, vous pouvez ajouter /permissions et des paramètres de requête à l’URL d’installation. Cela permet aux utilisateurs d’accorder votre GitHub App accès aux référentiels auxquels vous OAuth app avez déjà accès. Les paramètres de requête sont :

  • suggested_target_id: ID de l’utilisateur ou de l’organisation qui installe votre GitHub App. Ce paramètre est obligatoire.
  • repository_ids[] : ID de dépôt à sélectionner pour l’installation. En cas d’omission, tous les dépôts sont sélectionnés. Le nombre maximal de dépôts pouvant être pré-sélectionnés s’élève à 100. Pour obtenir la liste des référentiels auxquels votre OAuth app a accès, utilisez les points de terminaison Lister les référentiels de l’utilisateur authentifié et Lister les référentiels de l’organisation.

Par exemple : https://github.com/apps/YOUR_APP_NAME/installations/new/permissions?suggested_target_id=ID_OF_USER_OR_ORG&repository_ids[]=REPO_A_ID&repository_ids[]=REPO_B_ID.

Pour plus d’informations sur l’installation de GitHub Apps, consultez Installation d’une application GitHub à partir de GitHub Marketplace pour votre compte personnel, Installation d’une application GitHub à partir de GitHub Marketplace pour vos organisations,Installation d’une application GitHub à partir d’un tiers et Installation de votre propre application GitHub.

Inviter les utilisateurs à autoriser votre application

Si vous souhaitez faire GitHub App des demandes d’API pour le compte d’un utilisateur, l’utilisateur doit autoriser l’application. Quand un utilisateur autorise une application, il lui accorde l’autorisation d’agir en son nom et il accorde les autorisations de compte demandées par l’application. Si l’application est installée sur un compte d’organisation, chaque utilisateur de cette organisation doit autoriser l’application pour qu’elle agisse en son nom.

Pour inviter les utilisateurs à autoriser votre application, guidez-les à travers le flux d’application web ou le flux d’appareil. Pour plus d’informations, consultez « Génération d’un jeton d’accès utilisateur pour une application GitHub ».

Pour plus d’informations sur l’autorisation GitHub Apps, consultez Autorisation des applications GitHub.

Encourager vos utilisateurs à révoquer OAuth app l’accès

Vous devez également encourager vos utilisateurs à révoquer l’autorisation d’accès à votre ancien OAuth app. Cela vous aidera à abandonner complètement votre OAuth app et contribuera à protéger les données de vos utilisateurs. Pour plus d’informations, consultez « Examen de vos applications autorisées OAuth ».

Mettre à jour l’interface ou la documentation

Vous devez mettre à jour toute interface utilisateur ou documentation liée à votre application pour refléter la modification d’un OAuth app à GitHub App.

6. Supprimer les webhooks de votre ancien OAuth app

Lorsqu’un utilisateur installe votre GitHub App et accorde l’accès à un dépôt, vous devez supprimer tous les webhooks de votre ancien OAuth app. Si votre nouveau GitHub App et votre ancien OAuth app réagissent aux webhooks pour le même événement, l’utilisateur peut observer un comportement en double.

Pour supprimer des webhooks de dépôt, vous pouvez écouter le webhook installation_repositories avec l’action added. Lorsque votre GitHub App reçoit cet événement, vous pouvez utiliser l’API REST pour supprimer le webhook de ces dépôts pour votre OAuth app. Pour plus d’informations, consultez « Événements et charges utiles du webhook » et « Points de terminaison d’API REST pour les webhooks du référentiel ».

De même, pour supprimer des webhooks d’organisation, vous pouvez écouter le webhook installation avec l’action created. Lorsque votre GitHub App reçoit cet événement pour une organisation, vous pouvez utiliser l’API REST pour supprimer le webhook de cette organisation et des dépôts correspondants pour votre OAuth app. Pour plus d’informations, consultez Événements et charges utiles du webhook, Points de terminaison d’API REST pour les webhooks de l'organisation et Points de terminaison d’API REST pour les webhooks du référentiel.

7. Supprimer votre ancien OAuth app

Une fois que vos utilisateurs ont migré vers votre nouveau GitHub App, vous devez supprimer votre ancien OAuth app. Cela permet d’éviter les abus des informations d’identification OAuth app. Cette action révoque également toutes les OAuth appautorisations restantes. Pour plus d’informations, consultez « Suppression d’une application OAuth ». Si votre OAuth app est répertorié sur GitHub Marketplace, vous devrez peut-être contacter Support GitHub pour supprimer d’abord votre application de la place de marché.