Migration d’applications OAuth vers des applications

Dans cet article

Les Apps sont la méthode recommandée pour l’intégration à . Les Apps offrent de nombreux avantages par rapport aux 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  ».

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

Familiarisez-vous de nouveau avec le code de votre OAuth app. Les demandes d’API que fait votre OAuth app vous aideront à décider des autorisations à sélectionner pour votre App.

Par ailleurs, quelques points de terminaison d’API REST ne sont pas disponibles pour les OAuth apps. Vérifiez que tous les points de terminaison REST que vous utilisez sont disponibles pour les Apps en consultant « Points de terminaison disponibles pour les jetons d’accès d’installation d’application  ».

Inscrivez une nouvelle App. Pour plus d’informations, consultez « Inscription d’une application  ».

Par rapport à une OAuth app, vous avez un plus grand contrôle sur les paramètres d’une App. Voici quelques ajouts clés :

  • Contrairement à une OAuth app qui agit toujours au nom d’un utilisateur, vous pouvez faire en sorte que votre App effectuent des actions en son nom ou au nom d’un utilisateur. Si vous ne souhaitez pas que votre nouvelle App effectue des actions au nom 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  ».

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

  • Avec une OAuth app, vous demandez des étendues lorsqu’un utilisateur autorise votre application. Avec une 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. De plus, ces autorisations sont mappées à des points de terminaison d’API REST et à des événements de webhook, ce qui vous permet de déterminer facilement les autorisations dont votre App a 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  ».

Une fois que vous avez inscrit une App, adaptez le code de votre ancienne OAuth app pour utiliser votre nouvelle App.

Vous devez mettre à jour le code de votre application pour gérer l’authentification d’API pour votre App. Une App peut s’authentifier de trois manières :

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

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

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 App, consultez « Utilisation de webhooks avec des applications  » et « Génération d’une application qui répond aux événements de webhook ».

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

Si vous souhaitez que d’autres comptes puissent utiliser votre nouvelle App, assurez-vous que votre application est publique.Pour plus d’informations, consultez « Rendre une application publique ou privée ».

Une fois que votre nouvelle App est prête, demandez aux utilisateurs de votre ancienne OAuth app de migrer vers votre nouvelle App. Il n’existe pas de moyen d’effectuer une migration automatique de vos utilisateurs. Chaque utilisateur doit installer et/ou autoriser votre App lui-même.

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

Si vous souhaitez que votre App effectue des demandes d’API en son nom ou accède aux ressources d’organisation ou de dépôt, l’utilisateur doit installer votre App. Lorsqu’un utilisateur installe une App sur son compte ou organisation, il choisit les dépôts auxquels l’application peut accéder et lui accorde les autorisations d’organisation et de dépôt qu’elle a demandées.

Pour aider vos utilisateurs à installer votre App, vous pouvez ajouter un lien vers la page web de votre application sur lequel les utilisateurs peuvent cliquer pour installer l’ App. Le format de l’URL d’installation est http(s)://HOSTNAME/-apps/YOUR_APP_NAME/installations/new. Remplacez YOUR_APP_NAME par le nom « slugifié » de votre App, que vous trouverez dans le champ « Lien public » de la page des paramètres de votre App.

Pour présélectionner les dépôts auxquels votre OAuth app avait accès, vous pouvez ajouter /permissions et les paramètres de requête à l’URL d’installation. Cela permet aux utilisateurs d’accorder à votre App l’accès aux dépôts auxquels votre OAuth app a 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 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 dépôts auxquels votre OAuth app a accès, utilisez les points de terminaison Lister les dépôts de l’utilisateur authentifié et Lister les dépôts de l’organisation.

Par exemple : http(s)://HOSTNAME/-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 Apps, consultez « Installation d’une application à partir d’un tiers » et « Installation de votre propre application  ».

Si vous souhaitez que votre App effectue des demandes d’API au nom d’un utilisateur, celui-ci 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  ».

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

Vous devez également encourager vos utilisateurs à révoquer l’accès à votre ancienne OAuth app. Cela vous permet de finaliser la transition de votre OAuth app et de garder les données de vos utilisateurs en sécurité. Pour plus d’informations, consultez « Examen de vos applications autorisées OAuth ».

Vous devez mettre à jour l’interface utilisateur ou la documentation relative à votre application pour refléter le remplacement d’une OAuth app par une App.

Lorsqu’un utilisateur installe votre App et lui accorde l’accès à un dépôt, vous devez supprimer tous les webhooks de votre ancienne OAuth app. Si votre nouvelle App et votre ancienne OAuth app répondent 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 App reçoit cet événement, vous pouvez utiliser l’API REST pour supprimer le webhook sur 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 App reçoit cet événement pour une organisation, vous pouvez utiliser l’API REST pour supprimer le webhook sur cette organisation et les 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.

Une fois que vos utilisateurs ont migré vers votre nouvelle App, vous devez supprimer votre ancienne OAuth app. Cela permet d’éviter une mauvaise utilisation des informations d’identification de l’OAuth app. Cette action révoque également toutes les autorisations restantes de l’OAuth app. Pour plus d’informations, consultez « Suppression d’une application OAuth ». Si votre OAuth app est référencée sur Marketplace, vous devrez peut-être contacter le Support pour supprimer d’abord votre application de la Place de marché.