Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
 

 

Identification et autorisation des utilisateurs pour les applications GitHub

In this article

Votre application GitHub peut effectuer des actions pour le compte d’un utilisateur, comme la création d’un problème, la création d’un déploiement et l’utilisation d’autres points de terminaison pris en charge.

Remarque : la fonctionnalité d’expiration des jetons d’accès utilisateur est actuellement facultative et peut être modifiée. Pour activer ou désactiver la fonctionnalité d’expiration des jetons d’accès utilisateur à serveur, consultez « Activation des fonctionnalités facultatives pour les applications ». Pour plus d’informations, consultez « Expiration des jetons d’accès utilisateur à serveur pour les applications GitHub ».

Quand votre application GitHub agit au nom d’un utilisateur, elle effectue des requêtes utilisateur à serveur. Ces requêtes doivent être autorisées à l’aide du jeton d’accès d’un utilisateur. Les requêtes utilisateur à serveur incluent la demande de données pour un utilisateur, par exemple l’identification des dépôts à afficher pour un utilisateur particulier. Ces requêtes incluent également les actions déclenchées par un utilisateur, par exemple l’exécution d’une build.

Pour sécuriser davantage les jetons d’accès utilisateur à serveur, vous pouvez utiliser des jetons d’accès qui expirent au bout de 8 heures ainsi qu’un jeton d’actualisation qui peut être échangé contre un nouveau jeton d’accès. Pour plus d’informations, consultez « Actualisation des jetons d’accès utilisateur à serveur ».

Identification des utilisateurs sur votre site

Pour autoriser les utilisateurs des applications standard qui s’exécutent dans le navigateur, utilisez le flux d’application web.

Pour autoriser les utilisateurs à accéder aux applications sans périphérique de contrôle et sans accès direct au navigateur, par exemple les outils CLI ou les gestionnaires d’informations d’identification Git, utilisez le flux d’appareil. Le flux d’appareil utilise le type d’autorisation d’appareil OAuth 2.0.

Flux d’application web

Avec le flux d’application web, le processus d’identification des utilisateurs sur votre site est le suivant :

  1. Les utilisateurs sont redirigés pour fournir leur identité GitHub
  2. Les utilisateurs sont redirigés vers votre site par GitHub
  3. Votre application GitHub accède à l’API avec le jeton d’accès de l’utilisateur

Si vous sélectionnez Demander l’autorisation utilisateur (OAuth) durant l’installation au moment de la création ou de la modification de votre application, l’étape 1 est effectuée durant l’installation de l’application. Pour plus d’informations, consultez « Autorisation des utilisateurs durant l’installation ».

1. Demander l’identité GitHub d’un utilisateur

Redirigez l’utilisateur vers l’URL suivante dans son navigateur :

GET http(s)://HOSTNAME/login/oauth/authorize

Quand votre application GitHub spécifie un paramètre login, elle invite les utilisateurs à indiquer un compte spécifique qui leur permettra de se connecter et d’autoriser votre application.

Paramètres

NomTypeDescription
client_idstringObligatoire. ID client de votre application GitHub. Vous pouvez le trouver dans les Paramètres d’application GitHub quand vous sélectionnez votre application. Remarque : L’ID d’application et l’ID client ne sont pas les mêmes, et ne sont pas interchangeables.
redirect_uristringURL de votre application où les utilisateurs sont redirigés après l’autorisation. Elle doit correspondre exactement à l’une des URL que vous avez fournies en tant qu’URL de rappel au moment de la configuration de votre application GitHub, et ne peut contenir aucun paramètre supplémentaire.
statestringDoit contenir une chaîne aléatoire pour la protection contre les attaques par falsification et peut contenir d’autres données arbitraires.
loginstringSuggère un compte spécifique à utiliser pour la connexion et l’autorisation de l’application.
allow_signupstringIndique si les utilisateurs non authentifiés se voient offrir ou non la possibilité de s’inscrire à GitHub durant le flux OAuth. Par défaut, il s’agit de true. Utilisez false quand une stratégie interdit les inscriptions.

Remarque : Vous n’avez pas besoin de fournir d’étendues dans votre demande d’autorisation. Contrairement au protocole OAuth classique, le jeton d’autorisation est limité aux autorisations associées à votre application GitHub et à celles de l’utilisateur.

2. Les utilisateurs sont redirigés vers votre site par GitHub

Si l’utilisateur accepte votre requête, GitHub effectue une redirection vers votre site avec un code temporaire dans un paramètre de code ainsi que l’état que vous avez fourni à l’étape précédente dans un paramètre state. Si les états ne correspondent pas, cela signifie que la requête a été créée par un tiers et que le processus doit être abandonné.

Remarque : Si vous sélectionnez Demander l’autorisation utilisateur (OAuth) durant l’installation au moment de la création ou de la modification de votre application, GitHub retourne un code temporaire que vous devez échanger contre un jeton d’accès. Le paramètre state n’est pas retourné quand GitHub lance le flux OAuth durant l’installation de l’application.

Échangez ce code contre un jeton d’accès. Quand les jetons ayant un délai d’expiration sont activés, le jeton d’accès expire après 8 heures, et le jeton d’actualisation 6 mois. Chaque fois que vous actualisez le jeton, vous obtenez un nouveau jeton d’actualisation. Pour plus d’informations, consultez « Actualisation des jetons d’accès utilisateur à serveur ».

Les jetons d’accès utilisateur ayant un délai d’expiration sont une fonctionnalité facultative et sujette à changement. Pour activer la fonctionnalité d’expiration des jetons d’accès utilisateur à serveur, consultez « Activation des fonctionnalités facultatives pour les applications ».

Envoyez une requête au point de terminaison suivant pour recevoir un jeton d’accès :

POST http(s)://HOSTNAME/login/oauth/access_token

Paramètres

NomTypeDescription
client_idstringObligatoire. ID client de votre application GitHub.
client_secretstringObligatoire. Secret client de votre application GitHub.
codestringObligatoire. Code que vous avez reçu en réponse à l’étape 1.
redirect_uristringURL de votre application où les utilisateurs sont redirigés après l’autorisation. Elle doit correspondre exactement à l’une des URL que vous avez fournies en tant qu’URL de rappel au moment de la configuration de votre application GitHub, et ne peut contenir aucun paramètre supplémentaire.

response

Par défaut, la réponse prend la forme suivante. Les paramètres de réponse expires_in, refresh_token et refresh_token_expires_in sont retournés uniquement quand vous activez les jetons d’accès utilisateur à serveur ayant un délai d’expiration.

{
  "access_token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
  "expires_in": 28800,
  "refresh_token": "ghr_1B4a2e77838347a7E420ce178F2E7c6912E169246c34E1ccbF66C46812d16D5B1A9Dc86A1498",
  "refresh_token_expires_in": 15811200,
  "scope": "",
  "token_type": "bearer"
}

3. Votre application GitHub accède à l’API avec le jeton d’accès de l’utilisateur

Le jeton d’accès de l’utilisateur permet à l’application GitHub d’effectuer des requêtes auprès de l’API au nom d’un utilisateur.

Authorization: Bearer OAUTH-TOKEN
GET http(s)://HOSTNAME/api/v3/user

Par exemple, avec curl, vous pouvez définir l’en-tête d’autorisation comme ceci :

curl -H "Authorization: Bearer OAUTH-TOKEN" http(s)://HOSTNAME/api/v3/user

Flux d’appareil

Remarque : Le flux d’appareil est en version bêta publique et est susceptible de changer.

Le flux d’appareil vous permet d’autoriser des utilisateurs pour une application sans périphérique de contrôle, par exemple un outil CLI ou un gestionnaire d’informations d’identification Git.

Pour plus d’informations sur l’autorisation des utilisateurs à l’aide du flux d’appareil, consultez « Autorisation des applications OAuth ».

Vérifier les ressources de l’installation auxquelles un utilisateur peut accéder

Une fois que vous disposez d’un jeton OAuth pour un utilisateur, vous pouvez vérifier les installations auxquelles cet utilisateur peut accéder.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations

Vous pouvez également vérifier quels sont les dépôts accessibles à un utilisateur pour une installation.

Authorization: Bearer OAUTH-TOKEN
GET /user/installations/:installation_id/repositories

Pour plus d’informations, consultez Lister les installations d’applications accessibles au jeton d’accès utilisateur et Lister les dépôts accessibles au jeton d’accès utilisateur.

Gestion d’une autorisation d’application GitHub révoquée

Si un utilisateur révoque son autorisation pour une application GitHub, l’application reçoit le webhook github_app_authorization par défaut. Les applications GitHub ne peuvent pas se désabonner de cet événement. N’importe quel utilisateur peut révoquer l’autorisation dont il dispose pour une application GitHub à partir de la page des paramètres de son compte GitHub. La révocation de l’autorisation relative à une application GitHub ne désinstalle pas l’application. Vous devez programmer votre application GitHub afin que lorsqu’elle reçoit ce webhook, elle cesse d’appeler l’API pour le compte de la personne qui a révoqué le jeton. Si votre application GitHub continue d’utiliser un jeton d’accès révoqué, elle reçoit l’erreur 401 Bad Credentials.

Autorisations au niveau de l’utilisateur

Vous pouvez ajouter des autorisations au niveau de l’utilisateur à votre application GitHub pour accéder aux ressources utilisateur (par exemple les e-mails des utilisateurs). Ces autorisations sont octroyées par des utilisateurs individuels dans le cadre du flux d’autorisation utilisateur. Les autorisations au niveau de l’utilisateur diffèrent des autorisations au niveau du dépôt et de l’organisation, qui sont octroyées au moment de l’installation dans un compte d’organisation ou personnel.

Vous pouvez sélectionner des autorisations au niveau de l’utilisateur dans les paramètres de votre application GitHub, dans la section Autorisations utilisateur de la page Autorisations et webhooks. Pour plus d’informations sur la sélection des autorisations, consultez « Modification des autorisations d’une application GitHub ».

Quand un utilisateur installe votre application dans son compte, l’invite d’installation liste les autorisations au niveau de l’utilisateur demandées par votre application, et explique que l’application peut demander ces autorisations à des utilisateurs individuels.

Dans la mesure où les autorisations au niveau de l’utilisateur sont octroyées individuellement, vous pouvez les ajouter à votre application existante sans demander aux utilisateurs d’effectuer une mise à niveau. Toutefois, vous devez faire passer les utilisateurs existants par le flux d’autorisation utilisateur afin d’activer la nouvelle autorisation, et d’obtenir un nouveau jeton utilisateur à serveur pour ces requêtes.

Requêtes utilisateur à serveur

Bien que la majeure partie des interactions de votre API doive se produire via des jetons d’accès d’installation serveur à serveur, certains points de terminaison vous permettent d’effectuer des actions via l’API à l’aide d’un jeton d’accès utilisateur. Votre application peut effectuer les requêtes suivantes à l’aide des points de terminaison GraphQL ou REST.

Points de terminaison pris en charge

Exécutions de vérifications

Suites de vérifications

Codes de conduite

États de déploiement

Déploiements

Événements

Flux

Objets blob Git

Validations Git

Références Git

Étiquettes Git

Arborescences Git

Modèles gitignore

Installations

Personnes responsables d’un problème

Commentaires de problème

Événements de problème

Chronologie de problème

Problèmes

Étiquettes

Licences

Markdown

Meta

Étapes majeures

Crochets d’organisation

Membres de l’organisation

Collaborateurs externes de l’organisation

Crochets de préréception d’une organisation

Projets d’équipe de l’organisation

Dépôts d’équipe de l’organisation

Équipes de l’organisation

Organisations

Collaborateurs de projet

Projets

Commentaires de tirage

Événements de revue de demande de tirage

Demandes de revue de demande de tirage

Revues de demande de tirage

Tirages

Réactions

Référentiels

Activité d’un dépôt

Branches d’un dépôt

Collaborateurs d’un dépôt

Commentaires de commit d’un dépôt

Commits d’un dépôt

Communauté d’un dépôt

Contenu d’un dépôt

Dispatch des événements d’un dépôt

Crochets d’un dépôt

Invitations à un dépôt

Clés d’un dépôt

Pages d’un dépôt

Crochets de préréception d’un dépôt

Mises en production d’un dépôt

Statistiques d’un dépôt

Root

Rechercher

États

Discussions d’équipe

Rubriques

E-mails utilisateur

Abonnés d’un utilisateur

Clés GPG d’un l’utilisateur

Clés publiques de l’utilisateur

Utilisateurs

Pour aller plus loin