🌐 Meilleures pratiques pour la création d’une application GitHub - Documentation 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. Les clés privées sont utilisées pour générer des jetons d'accès à l'installation, tandis que les secrets clients sont utilisés pour obtenir 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 des clés privées, des jetons et des secrets clients en toute sécurité. Cependant, le mécanisme de stockage et sa sécurité relative dépendent de votre architecture d'intégration et de la plateforme sur laquelle elle fonctionne. 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. Il doit être stocké en toute sécurité et ne jamais être partagé à grande échelle.

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, cette méthode n’est pas aussi sécurisée 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 (par opposition à une exécution 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 qui ne sont plus utilisées. Pour plus d’informations, consultez « Gestion des clés privées pour les applications GitHub ».

Clés secrètes client

Les secrets client sont nécessaires pour générer des jetons d'accès utilisateur pour votre application, sauf si celle-ci utilise le flux de l'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 client confidentiel, c'est-à-dire qu'elle peut sécuriser le secret client en toute sécurité, envisagez de stocker votre secret client dans un coffre-fort de clés, tel queAzure Key Vault, ou sous forme de variable d'environnement cryptée ou de secret sur votre serveur.

Si votre application est un client public (une application native qui s’exécute sur l’appareil de l’utilisateur, l’utilitaire CLI ou l’application web monopage), vous ne pouvez pas sécuriser votre clé secrète client. Vous devrez expédier la clé secrète client dans le code de l’application, et vous devez utiliser PKCE pour mieux sécuriser le flux d’authentification. Vous devez faire preuve de prudence si vous prévoyez de contrôler l'accès à vos propres services à l'aide de jetons générés par votre application, car les clients publics sont facilement usurpables : n'importe qui peut réutiliser l'ID client de votre application pour se connecter.

N’activez pas le flux d’appareil sans raison

Il est préférable d’utiliser le code d’autorisation avec PKCE sur le flux d’appareil, si vous êtes intéressé par l’utilisation de la clé secrète client dans un client public. Le flux d’appareil ne nécessite pas du tout d’URI de redirection, ce qui signifie qu’un attaquant peut utiliser le flux d’appareil pour emprunter à distance l’identité de votre application dans le cadre d’une attaque par hameçonnage. Pour cette raison, n'activez pas le flux de périphériques pour votre application, sauf si vous utilisez l'application dans un environnement contraint (CLI, périphériques IoT ou systèmes sans affichage).

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.

Vérifiez minutieusement, durablement et fréquemment l’autorisation

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. Vous devez vérifier régulièrement que leurs adhésions, leurs accès et leur statut d’authentification unique actuel leur permettent toujours d’accéder à votre application et aux ressources qu’elle protège.

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 connectez un utilisateur, vous devez suivre les organisations pour lesquelles le jeton de l’utilisateur est autorisé. Cela peut changer au fil du temps après la connexion, car les utilisateurs peuvent être supprimés des organisations. 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 devez utiliser régulièrement le point de terminaison GET /user/installations de l’API REST pour vérifier à quelles organisations un jeton d’accès utilisateur a accès. Si l’utilisateur n’est pas autorisé à accéder à une organisation, vous devez empêcher son accès aux données appartenant à l’organisation au sein de votre propre application jusqu’à ce qu’il procède à l’authentification unique SAML ou rejoigne l’organisation. 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 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.

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

Dans cet article