À propos de GitHub Apps et OAuth apps
En général, les GitHub Apps sont préférables aux OAuth apps. Les GitHub Apps utilisent des autorisations de granularité fine, donnent à l’utilisateur davantage de contrôle sur les référentiels auxquels l’application peut accéder et utilisent des jetons à courte durée de vie. Ces propriétés contribuent à durcir la sécurité de votre application, car elles limitent les dommages potentiels en cas de divulgation des informations d’identification de votre application.
Comme les OAuth apps, les GitHub Apps peuvent toujours utiliser OAuth 2.0, générer un type de jeton OAuth (appelé jeton d’accès utilisateur) et effectuer des actions au nom d’un utilisateur. Toutefois, les GitHub Apps peuvent aussi agir indépendamment d’un utilisateur. Cela est utile pour les automatisations qui ne nécessitent pas d’entrée utilisateur. L’application pourra continuer de fonctionner même si la personne ayant initialement installé l’application sur une organisation quitte cette organisation.
Les GitHub Apps ont des webhooks intégrés centralisés. Les GitHub Apps peuvent recevoir des événements de webhook pour l’ensemble des référentiels et des organisations auxquels l’application a accès. À l’inverse, les OAuth apps doivent configurer des webhooks individuellement pour chaque référentiel et chaque organisation.
La limite de débit pour les GitHub Apps utilisant un jeton d’accès d’installation s’adapte au nombre de référentiels et au nombre d’utilisateurs dans l’organisation. À l’inverse, les OAuth apps ont des limites de débit inférieures et ne sont pas évolutives.
Il y a une situation où les OAuth app sont préférables aux GitHub App. Si votre application a besoin d’un accès aux ressources de niveau entreprise, telles que l’objet d’entreprise lui-même, vous devez utiliser une OAuth app parce qu’une GitHub App ne peut pas recevoir d’autorisations sur une entreprise. Les GitHub Apps peuvent toujours accéder aux ressources d’organisation et de référentiel appartenant à l’entreprise.
Pour plus d’informations sur les GitHub Apps, consultez « À propos de la création d’applications GitHub ».
Pour plus d’informations sur la migration d’une OAuth app existante vers une GitHub App, consultez « Migration d’applications OAuth vers des applications GitHub ».
Qui peut installer des applications GitHub et autoriser OAuth apps ?
Vous pouvez installer des applications GitHub dans votre compte personnel ou dans des organisations dont vous êtes propriétaire. Si vous disposez d’autorisations d’administrateur dans un dépôt, vous pouvez installer des applications GitHub sur des comptes d’organisation. Si une application GitHub est installée dans un dépôt et nécessite des autorisations de l’organisation, le propriétaire de celle-ci doit approuver l’application.
Par défaut, seuls les propriétaires d’organisation peuvent gérer les paramètres des applications GitHub dans une organisation. Pour permettre à d’autres utilisateurs de modifier les paramètres de développeur des applications GitHub appartenant à l’organisation, un propriétaire peut leur accorder des autorisations de gestionnaire d’applications GitHub. Les gestionnaires d’applications GitHub ne peuvent pas gérer les applications tierces. Pour plus d’informations sur l’ajout et la suppression de gestionnaires d’applications GitHub dans votre organisation, consultez « Rôles dans une organisation ».
Par contre, des utilisateurs autorisent des OAuth apps, ce qui donne à l’application la capacité d’agir en tant qu’utilisateur authentifié. Par exemple, vous pouvez autoriser une OAuth app qui trouve toutes les notifications pour l’utilisateur authentifié. Vous pouvez toujours révoquer des autorisations à partir d’une OAuth app.
Avertissement : La révocation de toutes les autorisations d’une OAuth app supprime toutes les clés SSH générées au nom de l’utilisateur par l’application, y compris les clés de déploiement.
| Applications GitHub | OAuth apps |
|---|---|
| Pour installer une application GitHub sur une organisation, vous devez être propriétaire d’organisation, ou disposer d’autorisations d’administrateur dans un dépôt. Si une application GitHub est installée dans un dépôt et nécessite des autorisations de l’organisation, le propriétaire de celle-ci doit approuver l’application. | Vous pouvez autoriser l’accès d’une OAuth app aux ressources. |
| Vous pouvez installer une application GitHub sur votre dépôt personnel. | Vous pouvez autoriser l’accès d’une OAuth app aux ressources. |
| Pour désinstaller une application GitHub et supprimer l’accès à celle-ci, vous devez être propriétaire d’organisation, propriétaire de dépôt personnel ou disposer d’autorisations d’administrateur dans un dépôt. | Vous pouvez supprimer un jeton d’accès OAuth pour supprimer l’accès. |
| Pour demander l’installation d’une application GitHub, vous devez être propriétaire d’organisation, ou disposer d’autorisations d’administrateur dans un dépôt. | Si une stratégie d’application d’organisation est active, tout membre d’une organisation peut demander d’installer une OAuth app sur une organisation. Un propriétaire de l’organisation doit approuver ou rejeter la demande. |
À quoi ont accès les applications GitHub et OAuth apps ?
Des propriétaires de compte peuvent utiliser une GitHub App dans un compte sans octroyer d’accès à un autre. Par exemple, vous pouvez installer un service de build tiers sur l’organisation de votre employeur, mais décider de ne pas accorder à ce service de build l’accès aux dépôts dans votre compte personnel. Une application GitHub reste installée si la personne qui l’a configurée quitte l’organisation.
Une OAuth app autorisée a accès à toutes les ressources accessibles de l’utilisateur ou du propriétaire de l’organisation.
| Applications GitHub | OAuth apps |
|---|---|
| L’installation d’une application GitHub lui octroie l’accès aux référentiels choisis d’un compte d’utilisateur ou d’organisation. | L’autorisation d’une OAuth app autorise l’accès de l’application aux ressources accessibles de l’utilisateur. Par exemple, les dépôts auxquels elles peuvent accéder. |
| Le jeton d’installation d’une application GitHub perd l’accès aux ressources si un administrateur supprime des dépôts de l’installation. | Un jeton d’accès OAuth perd l’accès aux ressources quand l’utilisateur perd l’accès, par exemple, quand il perd l’accès en écriture à un dépôt. |
| Les jetons d’accès d’installation sont limités aux dépôts spécifiés avec les autorisations choisies par le créateur de l’application. | Un jeton d’accès OAuth est limité par le biais d’étendues. |
| Les applications GitHub peuvent demander un accès séparé à des problèmes et à des demandes de tirage sans accéder au contenu réel du dépôt. | Les OAuth apps doivent demander l’étendue repo pour obtenir l’accès à des problèmes, à des demandes de tirage ou à tout ce qui appartient au référentiel. |
| Les applications GitHub ne sont pas soumises aux stratégies d’application de l’organisation. Une application GitHub a uniquement accès aux dépôts auxquels le propriétaire d’une organisation a accordé cet accès. | Si une stratégie d’application d’organisation est active, seul le propriétaire d’une organisation peut autoriser l’installation d’une OAuth app. Si elle est installée, l’application OAuth app obtient l’accès à tout ce qui est visible par le jeton que détient le propriétaire de l’organisation au sein de l’organisation approuvée. |
| Une application GitHub reçoit un événement de webhook quand une installation est modifiée ou supprimée. Cela indique au créateur de l’application quand celle-ci a reçu plus ou moins d’accès aux ressources d’une organisation. | Les OAuth apps peuvent perdre l’accès à une organisation ou à un référentiel à tout moment si l’utilisateur octroyant l’accès le modifie. L’application OAuth app ne vous informe pas quand elle perd l’accès à une ressource. |
Identification basée sur un jeton
Remarque : les applications GitHub peuvent également utiliser un jeton basé sur l’utilisateur. Pour plus d’informations, consultez « Authentification auprès d’une application GitHub pour le compte d’un utilisateur ».
| Applications GitHub | OAuth apps |
|---|---|
| Une application GitHub peut demander un jeton d’accès d’installation en utilisant une clé privée avec un format de jeton web JSON hors bande. | Une OAuth app peut échanger un jeton de demande contre un jeton d’accès après redirection via une demande web. |
| Un jeton d’installation identifie l’application en tant que bot d’applications GitHub, par exemple, @jenkins-bot. | Un jeton d’accès identifie l’application comme étant l’utilisateur qui a accordé le jeton à l’application, par exemple, @octocat. |
| Les jetons d’accès d’installation expirent après une période prédéfinie (actuellement 1 heure). | Les jetons OAuth restent actifs jusqu’à ce que le client les révoque. |
| Les GitHub Apps installées sur des organisations ou des dépôts sont soumises à des limites de taux qui s’adaptent en fonction du nombre d’installations. Pour plus d’informations, consultez « Limites de débit pour les applications GitHub ». | Les jetons OAuth utilisent la limitation de débit de l’utilisateur de 5 000 requêtes par heure. |
| Des augmentations de limite de débit peuvent être accordées au niveau des applications GitHub (ce qui affecte toutes les installations) et au niveau de l’installation individuelle. | Les augmentations de la limite de débit sont accordées par OAuth app. Chaque jeton accordé à cette OAuth app obtient la limite augmentée. |
| Les GitHub Apps peuvent s’authentifier pour le compte de l’utilisateur. Le flux d’autorisation est le même que le flux d’autorisation de l’OAuth app. Les jetons d’accès utilisateur peuvent expirer et être renouvelés avec un jeton d’actualisation. Pour plus d’informations, consultez « Actualisation des jetons d’accès utilisateur » et « Authentification auprès d’une application GitHub pour le compte d’un utilisateur ». | Le flux OAuth utilisé par les OAuth apps autorise une OAuth app pour le compte de l’utilisateur. C’est le même flux utilisé pour générer un jeton d’accès utilisateur d’GitHub App. |
Demande de niveaux d’autorisation pour des ressources
Contrairement aux OAuth apps, les applications GitHub ont des autorisations ciblées qui leur permettent de demander l’accès uniquement à ce dont elles ont besoin. Par exemple, une application d’intégration continue (CI) GitHub peut demander l’accès en lecture au contenu du dépôt, et l’accès en écriture à l’API d’état. Une autre application GitHub peut ne pas avoir d’accès en lecture ou en écriture au code, mais elle a toujours la possibilité de gérer des problèmes, des étiquettes et des jalons. Les OAuth apps ne peuvent pas utiliser d’autorisations granulaires.
| Access | Applications GitHub (autorisations readou write) | OAuth apps |
|---|---|---|
| Pour accéder aux dépôts publics | Le dépôt public doit être choisi lors de l’installation. | Étendue public_repo. |
| Pour accéder au code/contenu du dépôt | Contenu d’un dépôt | Étendue repo. |
| Pour accéder aux problèmes, étiquettes et jalons | Problèmes | Étendue repo. |
| Pour accéder aux demandes de tirage, étiquettes et jalons | Demandes de tirage | Étendue repo. |
| Pour accéder aux états de validation (pour les builds CI) | États de validation | Étendue repo:status. |
| Pour accéder aux déploiements et aux états de déploiement | Déploiements | Étendue repo_deployment. |
| Pour recevoir des événements via un webhook | Une application GitHub inclut un webhook par défaut. | Étendue write:repo_hook ou write:org_hook. |
Découverte d’un dépôt
| Applications GitHub | OAuth apps |
|---|---|
Les applications GitHub peuvent examiner /installation/repositories pour voir les dépôts auxquels l’installation peut accéder. | Les OAuth apps peuvent examiner /user/repos pour obtenir un affichage utilisateur ou /orgs/:org/repos pour obtenir un affichage d’organisation des référentiels accessibles. |
| Les applications GitHub reçoivent des webhooks lors de l’ajout ou de la suppression de dépôts de l’installation. | Les OAuth apps créent des webhooks d’organisation pour les notifications lors de la création d’un référentiel au sein d’une organisation. |
Webhooks
| Applications GitHub | OAuth apps |
|---|---|
| Par défaut, les applications GitHub Apps disposent d’un webhook unique qui reçoit les événements pour la réception desquels elles sont configurées, pour chaque dépôt auquel elles ont accès. | Les OAuth apps demandent l’étendue du webhook afin de créer un webhook de référentiels pour chaque référentiel à partir duquel elles ont besoin de recevoir des événements. |
| Les applications GitHub reçoivent certains événements de niveau organisation avec l’autorisation du membre de l’organisation. | Les OAuth apps demandent l’étendue du webhook de l’organisation afin de créer un webhook d’organisation pour chaque organisation à partir de laquelle elles ont besoin de recevoir des événements de niveau organisation. |
| Les webhooks sont automatiquement désactivés lorsque l’application GitHub est désinstallée. | Les webhooks ne sont pas automatiquement désactivés si le jeton d’accès d’une OAuth app est supprimé et qu’il n’existe aucun moyen de les nettoyer automatiquement. Vous devez demander aux utilisateurs de procéder manuellement. |
Accès à Git
| Applications GitHub | OAuth apps |
|---|---|
| Les applications GitHub demandent l’autorisation d’accéder au contenu des dépôts et d’utiliser votre jeton d’accès d’installation pour s’authentifier par le biais de Git basé sur HTTP. Pour plus d’informations, consultez « Génération d’un jeton d’accès d’installation pour une application GitHub ». | Les OAuth apps demandent l’étendue write:public_key et Créer une clé de déploiement via l’API. Vous pouvez ensuite utiliser cette clé pour exécuter des commandes Git. |
| Le jeton est utilisé en tant que mot de passe HTTP. | Le jeton est utilisé en tant que nom d’utilisateur HTTP. |
Comptes de machine et de bot
Les comptes d’utilisateur de machine sont des comptes personnels basés sur OAuth, qui distinguent les systèmes automatisés utilisant le système utilisateur de GitHub.
Les comptes de bot sont spécifiques des applications GitHub, et intégrés à chaque application GitHub.
| Applications GitHub | OAuth apps |
|---|---|
| Les bots d’application GitHub ne consomment pas de poste GitHub Enterprise. | Un compte d’utilisateur de machine consomme un poste GitHub Enterprise. |
| Étant donné qu’un bot d’application GitHub ne reçoit jamais de mot de passe, un client ne peut pas s’y connecter directement. | Un compte d’utilisateur de machine reçoit un nom d’utilisateur et un mot de passe que le client doit gérer et sécuriser. |