Meilleures pratiques pour la création d’une application GitHub

Sélectionner les autorisations minimales requises

Lorsque vous inscrivez une GitHub App, sélectionnez les autorisations minimales dont votre GitHub App a besoin. Si des clés ou des jetons pour votre application sont compromis, cela limitera la quantité de dommages susceptibles de se produire. Pour plus d’informations sur le choix des autorisations, consultez « Choix des autorisations pour une application GitHub ».

Lorsque votre GitHub App crée un jeton d’accès d’installation ou un jeton d’accès utilisateur, vous pouvez limiter davantage les dépôts auxquels l’application peut accéder et les autorisations dont dispose le jeton. Pour plus d’informations, consultez « Génération d’un jeton d’accès d’installation pour une application GitHub » et « Génération d’un jeton d’accès utilisateur pour une application GitHub ».

Rester sous la limite de débit

Abonnez-vous aux événements de webhook au lieu d’interroger l’API pour rechercher des données. Cela aidera votre GitHub App à rester dans la limite du taux d’API. Pour plus d’informations, consultez « Utilisation de webhooks avec des applications GitHub » et « Génération d’une application GitHub qui répond aux événements de webhook ».

Envisagez d’utiliser des requêtes conditionnelles pour vous aider à rester dans la limite de débit. Pour plus d’informations sur les demandes conditionnelles, consultez « Meilleures pratiques pour utiliser l'API REST ».

Si possible, envisagez d’utiliser des requêtes GraphQL consolidées plutôt que des requêtes d’API REST pour vous aider à respecter les limites de débit. Pour plus d’informations, consultez « Comparaison de l’API REST de GitHub et de l’API GraphQL » et « Documentation sur l’API GraphQL GitHub ».

Si vous atteignez une limite de débit et que vous devez réessayer une requête d’API, utilisez les en-têtes de réponse x-ratelimit-reset ou Retry-After. Si ces en-têtes ne sont pas disponibles, attendez une augmentation exponentielle du temps entre les nouvelles tentatives et levez une erreur après un nombre spécifique de nouvelles tentatives. Pour plus d’informations, consultez « Meilleures pratiques pour utiliser l'API REST ».

Sécuriser les informations d’identification de votre application

Vous pouvez générer une clé privée et une clé secrète client pour votre GitHub App. Avec ces informations d’identification, votre application peut générer des jetons d’accès d’installation, des jetons d’accès utilisateur et des jetons d’actualisation. Ces jetons peuvent être utilisés pour effectuer des demandes d’API pour le compte d’un utilisateur ou d’une installation d’application.

Vous devez stocker ces informations d’identification en toute sécurité. Le mécanisme de stockage dépend de votre architecture d’intégrations et de la plateforme sur laquelle elle s’exécute. En général, vous devez utiliser un mécanisme de stockage destiné à stocker des données sensibles sur la plateforme que vous utilisez.

Clés privées

La clé privée de votre GitHub App accorde l’accès à chaque compte sur lequel l’application est installée.

Envisagez de stocker la clé privée de votre GitHub App dans un coffre de clés, comme Azure Key Vault, et de la configurer en signature seule.

Vous pouvez également stocker la clé en tant que variable d’environnement. Cependant, cela n’est pas aussi fort que le stockage de la clé dans un coffre de clés. Si un attaquant obtient l’accès à l’environnement, il peut lire la clé privée et obtenir une authentification persistante en tant que GitHub App.

Vous ne devez jamais coder en dur votre clé privée dans votre application, même si votre code est stocké dans un dépôt privé. Si votre application est un client natif, une application côté client ou s’exécute sur un appareil utilisateur (plutôt que sur vos serveurs), vous ne devez jamais expédier votre clé privée avec votre application.

Vous ne devez pas générer plus de clés privées que nécessaire. Vous devez supprimer les clés privées dont vous n’avez plus besoin. Pour plus d’informations, consultez « Gestion des clés privées pour les applications GitHub ».

Clés secrètes client

Les secrets client sont utilisés pour générer des jetons d’accès utilisateur pour votre application, sauf si celle-ci utilise le flux d’appareil. Pour plus d’informations, consultez « Génération d’un jeton d’accès utilisateur pour une application GitHub ».

Si votre application est un site web ou une application web, envisagez de stocker votre clé secrète client dans un coffre de clés, comme Azure Key Vault, ou en tant que variable d’environnement chiffrée ou secret sur votre serveur.

Si votre application est un client natif, une application côté client ou s’exécute sur un appareil utilisateur (au lieu de s’exécuter sur vos serveurs), vous ne pouvez pas sécuriser votre clé secrète client. Vous devez faire preuve de prudence si vous envisagez de contrôler l’accès à vos propres services en fonction des jetons générés par votre application, car n’importe qui peut accéder à la clé secrète client pour générer un jeton.

Jetons d’accès d’installation, jetons d’accès utilisateur et jetons d’actualisation

Les jetons d’accès d’installation sont utilisés pour effectuer des requêtes d’API pour le compte d’une installation d’application. Les jetons d’accès utilisateur sont utilisés pour effectuer des requêtes d’API pour le compte d’un utilisateur. Les jetons d’actualisation sont utilisés pour régénérer les jetons d’accès utilisateur. Votre application peut utiliser sa clé privée pour générer un jeton d’accès d’installation. Votre application peut utiliser sa clé secrète client pour générer un jeton d’accès utilisateur et un jeton d’actualisation.

Si votre application est un site web ou une application web, vous devez chiffrer les jetons sur votre back-end et vous assurer qu’il existe une sécurité autour des systèmes qui peuvent accéder aux jetons. Envisagez de stocker les jetons d’actualisation dans un emplacement distinct des jetons d’accès actifs.

Si votre application est un client natif, une application côté client ou s’exécute sur un appareil utilisateur (par opposition à l’exécution sur vos serveurs), il se peut que vous ne puissiez pas sécuriser les jetons ainsi qu’une application qui s’exécute sur vos serveurs. Vous ne devez pas générer de jetons d’accès d’installation, car cela nécessite une clé privée. Au lieu de cela, vous devez générer des jetons d’accès utilisateur. Vous devez stocker les jetons via le mécanisme recommandé pour la plateforme de votre application, et garder à l’esprit que le mécanisme de stockage peut ne pas être entièrement sécurisé.

Utiliser le type de jeton approprié

Une GitHub Apps peut générer des jetons d’accès d’installation ou des jetons d’accès utilisateur afin d’effectuer des requêtes d’API authentifiées.

Les jetons d’accès d’installation attribuent l’activité à votre application. Ils sont utiles pour les automatisations qui agissent indépendamment des utilisateurs.

Les jetons d’accès utilisateur attribuent l’activité à un utilisateur et à votre application. Ils sont utiles pour effectuer des actions basées sur l’entrée utilisateur ou pour le compte d’un utilisateur.

Un jeton d’accès à l’installation est restreint en fonction des autorisations et de l’accès de l’GitHub App. Un jeton d’accès utilisateur est restreint en fonction de l’autorisation et de l’accès de l’GitHub App, ainsi que de l’autorisation et de l’accès de l’utilisateur. Par conséquent, si votre GitHub App effectue une action au nom d’un utilisateur, elle doit toujours utiliser un jeton d’accès utilisateur au lieu d’un jeton d’accès d’installation. Sinon, votre application peut permettre à un utilisateur de voir ou de faire des choses qu’il ne devrait pas être en mesure de voir ou faire.

Votre application ne doit jamais utiliser un personal access token ou un mot de passe GitHub pour s’authentifier.

Autoriser de manière complète et durable

Après la connexion d'un utilisateur, les développeurs d'applications doivent prendre des mesures supplémentaires pour s'assurer que l'utilisateur est censé avoir accès aux données de votre système. Chaque connexion nécessite de nouvelles vérifications concernant les abonnements, l'accès et l'état actuel du SSO.

Utiliser l’unique et durable `id` pour stocker l'utilisateur

Lorsqu’un utilisateur se connecte et effectue des actions dans votre application, vous devez mémoriser l’utilisateur qui a effectué cette action pour lui accorder l’accès aux mêmes ressources la prochaine fois qu’il se connecte.

Pour enregistrer correctement les utilisateurs dans votre base de données, utilisez toujours l’id de l’utilisateur. Cette valeur ne changera jamais pour l’utilisateur ou sera utilisée pour pointer vers un autre utilisateur. Ainsi, elle garantit que vous fournissez l’accès à l’utilisateur voulu. Vous pouvez trouver l’id de l’utilisateur avec le point de terminaison de l’API REST GET /user. Consultez « Points de terminaison d’API REST pour les utilisateurs ».

Si vous stockez des références aux référentiels, organisations et entreprises, utilisez leur id également pour vous assurer que vos liens restent exacts.

N’utilisez jamais d’identifiants qui peuvent changer au fil du temps, y compris les descripteurs d’utilisateur, les champs de données dynamiques d’organisation ou les adresses e-mail.

Valider l’accès de l’organisation pour chaque nouvelle authentification

Lorsque vous utilisez un jeton d’accès utilisateur, vous devez suivre les organisations pour lesquelles le jeton est autorisé. Si une organisation utilise l’authentification unique SAML et qu’un utilisateur n’a pas effectué d’authentification unique SAML, le jeton d’accès utilisateur n’aura pas accès à cette organisation. Vous pouvez utiliser le point de terminaison de l’API REST GET /user/installations pour vérifier les organisations auxquelles un jeton d’accès utilisateur a accès. Si l’utilisateur n’est pas autorisé à accéder à une organisation, vous devez lui refuser l’accès aux données appartenant à l’organisation dans votre propre application jusqu’à ce qu’il effectue une authentification unique SAML. Pour plus d’informations, consultez « Points d’accès à l’API REST pour les installations GitHub App ».

Stocker les données des utilisateurs dans le contexte de l'organisation et de l'entreprise

Outre le suivi de l’identité de l’utilisateur via le champ id, vous devez conserver les données relatives à l’organisation ou à l’entreprise dont relève chaque utilisateur. Cela vous permettra de vous assurer qu’il n’y a pas de fuite d’informations sensibles si un utilisateur change de rôle.

Par exemple :

Un utilisateur fait partie de l’organisation Mona, qui nécessite une authentification unique SAML, et se connecte à votre application après avoir effectué l’authentification unique. Votre application a désormais accès à ce que fait l’utilisateur dans Mona.
L’utilisateur extrait un nombre de codes d’un référentiel dans Mona et l’enregistre dans votre application à des fins d’analyse.
Ultérieurement, l’utilisateur bascule d’une tâche à l’autre et est supprimé de l’organisation Mona.

Quand l’utilisateur accède à votre application, peut-il toujours voir le code et l’analyse de l’organisation Mona dans son compte d’utilisateur ?

C’est pourquoi il est essentiel de suivre la source des données que votre application enregistre. Dans le cas contraire, votre application devient une menace à la protection des données pour les organisations qui seront susceptibles d’interdire votre application si elles ne peuvent lui faire confiance et ce afin de protéger correctement leurs données.

Expiration des jetons

GitHub vous encourage vivement à utiliser des jetons d’accès utilisateur qui expirent. Si vous avez précédemment refusé l’utilisation de jetons d’accès utilisateur qui expirent, mais que vous souhaitez réactiver cette fonctionnalité, consultez « Activation de fonctionnalités facultatives pour les applications GitHub ».

Les jetons d’accès d’installation expirent après une heure, les jetons d’accès utilisateur après huit heures et les jetons d’actualisation après six mois. Toutefois, vous pouvez également révoquer des jetons dès que vous n’en avez plus besoin. Pour plus d’informations, consultez « DELETE /installation/token » pour révoquer un jeton d’accès d’installation, et « DELETE /applications/{client_id}/token » pour révoquer un jeton d’accès utilisateur.

Mettre en cache des jetons

Les jetons d’accès d’utilisateur et les jetons d’accès d’installation sont destinés à être utilisés jusqu’à leur expiration. Vous devez mettre en cache les jetons que vous créez. Avant de créer un jeton, vérifiez votre cache pour voir si vous disposez déjà d’un jeton valide. La réutilisation des jetons rend votre application plus rapide, car celle-ci fait moins de demandes pour générer des jetons.

Planifier la gestion des violations de sécurité

Vous devez avoir un plan en place afin de pouvoir gérer les violations de sécurité en temps opportun.

Dans le cas où la clé privée ou le secret de votre application est compromis, vous devez générer une nouvelle clé ou un nouveau secret, mettre à jour votre application pour utiliser la nouvelle clé ou le nouveau secret, et supprimer votre ancienne clé ou ancien secret.

Dans le cas où les jetons d’accès d’installation, les jetons d’accès utilisateur ou les jetons d’actualisation sont compromis, vous devez immédiatement révoquer ces jetons. Pour plus d’informations, consultez « DELETE /installation/token » pour révoquer un jeton d’accès d’installation, et « DELETE /applications/{client_id}/token » pour révoquer un jeton d’accès utilisateur.

Effectuer des analyses de vulnérabilité régulières

Vous devez effectuer des analyses de vulnérabilité régulières pour votre application. Par exemple, vous pouvez configurer l’analyse du code et l’analyse des secrets pour le dépôt qui héberge le code de votre application. Pour plus d’informations, consultez « À propos de l’analyse du code » et « À propos de l’analyse des secrets ».

Choisir un environnement approprié

Si votre application s’exécute sur un serveur, vérifiez que votre environnement serveur est sécurisé et qu’il peut gérer le volume de trafic attendu pour votre application.

Abonnez-vous uniquement aux événements de webhook dont votre application a besoin. Cela permet de réduire la latence, car votre application ne reçoit pas de charges utiles dont elle n’a pas besoin.

Utiliser un secret de webhook

Vous devez définir un secret de webhook pour votre GitHub App et vérifier que la signature des événements webhook entrants correspond au secret. Cela permet de s’assurer que l’événement webhook entrant est un événement GitHub valide.

Pour plus d’informations, consultez « Utilisation de webhooks avec des applications GitHub ». Pour obtenir un exemple, consultez « Génération d’une application GitHub qui répond aux événements de webhook ».

Laisser aux utilisateurs le temps d’accepter les nouvelles autorisations

Lorsque vous ajoutez des autorisations de dépôt ou d’organisation à votre GitHub App, les utilisateurs pour lesquels l’application est installée sur leur compte personnel ou d’organisation reçoivent un e-mail les invitant à passer en revue les nouvelles autorisations. Tant que l’utilisateur n’approuve pas les nouvelles autorisations, son installation d’application ne recevra que les anciennes autorisations.

Lorsque vous mettez à jour les autorisations, vous devez envisager de rendre votre application rétrocompatible pour laisser à vos utilisateurs le temps d’accepter les nouvelles autorisations. Vous pouvez utiliser le webhook d’installation avec la propriété d’action new_permissions_accepted pour savoir quand les utilisateurs acceptent de nouvelles autorisations pour votre application.

Utiliser les services de manière sécurisée

Si votre application utilise des services tiers, ils doivent être utilisés de manière sécurisée :

Tous les services utilisés par votre application doivent avoir une connexion et un mot de passe uniques.
Les applications ne doivent pas partager de comptes de service tels que les services par e-mail ou de base de données pour gérer votre service SaaS.
Seuls les employés ayant des tâches administratives doivent avoir un accès administrateur à l’infrastructure qui héberge votre application.

Ajouter la journalisation et la supervision

Envisagez d’ajouter des fonctionnalités de journalisation et de supervision pour votre application. Un journal de sécurité peut inclure :

des événements d’authentification et d’autorisation
des changements de configuration de service
des lectures et écritures d’objets
des modifications d’autorisation d’utilisateur et de groupe
l’élévation du rôle à l’administrateur

Vos journaux doivent utiliser un horodatage cohérent pour chaque événement et enregistrer les utilisateurs, les adresses IP ou les noms d’hôte pour tous les événements journalisés.

Activer la suppression de données

Si votre GitHub App est disponible pour d’autres utilisateurs ou organisations, vous devez donner aux utilisateurs et propriétaires d’organisation un moyen de supprimer leurs données. Les utilisateurs ne doivent pas avoir besoin d’envoyer un e-mail ou d’appeler une personne du support technique pour supprimer leurs données.