Génération d’un jeton d’accès utilisateur pour une application GitHub

À propos des jetons d’accès utilisateur

Un jeton d’accès utilisateur est un type de jeton OAuth. Contrairement à un jeton OAuth traditionnel, le jeton d’accès utilisateur n’utilise pas d’étendues. À la place, il utilise des autorisations affinées. Un jeton d’accès utilisateur dispose uniquement des autorisations dont disposent l’utilisateur et l’application. Par exemple, si l’application a reçu l’autorisation d’écrire le contenu d’un dépôt, mais que l’utilisateur peut uniquement lire le contenu, le jeton d’accès utilisateur peut uniquement lire le contenu.

De même, un jeton d’accès utilisateur ne peut accéder qu’aux ressources auxquelles l’utilisateur et l’application peuvent accéder. Par exemple, si une application se voit accorder l’accès aux dépôts A et B, et que l’utilisateur peut accéder aux dépôts B et C, le jeton d’accès utilisateur peut accéder au dépôt B, mais pas aux dépôts A ou C. Vous pouvez utiliser l’API REST pour savoir à quelles installations et à quels dépôts d’une installation un jeton d’accès utilisateur peut accéder. Pour plus d’informations, consultez GET /user/installations et GET /user/installations/{installation_id}/repositories dans « Points d’accès à l’API REST pour les installations GitHub App ».

Lorsque vous effectuez des demandes d’API avec un jeton d’accès utilisateur, les limites de débit pour les jetons d’accès utilisateur s’appliquent. Pour plus d’informations, consultez « Limites de débit pour les applications GitHub ».

Par défaut, le jeton d’accès utilisateur expire au bout de 8 heures. Vous pouvez utiliser un jeton d’actualisation pour regénérer un jeton d’accès utilisateur. Pour plus d’informations, consultez « Actualisation des jetons d’accès utilisateur ».

Les utilisateurs peuvent révoquer leur autorisation d’une GitHub App. Pour plus d’informations, consultez « Expiration et révocation des jetons ». Si un utilisateur révoque son autorisation d’une GitHub App, l’application reçoit le webhook github_app_authorization. Les GitHub Apps ne peuvent pas se désabonner de cet événement. Si votre application reçoit ce webhook, vous devez arrêter d’appeler l’API au nom de l’utilisateur qui a révoqué le jeton. Si votre application continue d’utiliser un jeton d’accès révoqué, elle reçoit l’erreur 401 Bad Credentials. Pour plus d’informations sur ce webhook, consultez « Événements et charges utiles du webhook ».

Vous devez sécuriser les jetons d’accès utilisateur et les jetons d’actualisation. Pour plus d’informations, consultez « Meilleures pratiques pour la création d’une application GitHub ».

Utilisation du flux d’application web pour générer un jeton d’accès utilisateur

Si votre application s’exécute dans le navigateur, vous devez utiliser le flux d’application web pour générer un jeton d’accès utilisateur. Pour obtenir un tutoriel sur l’utilisation du flux d’application web, consultez « Création d’un bouton « Se connecter avec GitHub » avec une application GitHub App ».

1. Dirigez l’utilisateur vers cette URL et ajoutez tous les paramètres de requête nécessaires à partir de la liste de paramètres suivante : http(s)://HOSTNAME/login/oauth/authorize. Par exemple, cette URL spécifie les paramètres client_id et state : http(s)://HOSTNAME/login/oauth/authorize?client_id=12345&state=abcdefg.

   Paramètre de requête.	Type	Description
   client_id	string	Obligatoire. ID client de votre GitHub App. ID client est différent de l’ID de l’application. Vous pouvez trouver votre ID client dans la page Paramètres de votre application. Pour plus d’informations sur la navigation vers la page des paramètres pour votre GitHub App, consultez « Modification d’une inscription d’application GitHub ».
   redirect_uri	string	URL 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 comme « URL de rappel » dans les paramètres de votre application et ne peut pas contenir de paramètres supplémentaires.
   state	string	Lorsque la valeur est spécifiée, elle doit contenir une chaîne aléatoire pour la protection contre les attaques par falsification et peut également contenir d’autres données arbitraires.
   login	string	Lorsqu’il est spécifié, le flux d’application web invite les utilisateurs avec un compte spécifique qu’ils peuvent utiliser pour se connecter et autoriser votre application.
   allow_signup	boolean	Indique si les utilisateurs non authentifiés se voient offrir 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.

2. Si l’utilisateur accepte votre demande d’autorisation, GitHub redirige l’utilisateur vers l’une des URL de rappel des paramètres de votre application et fournit un paramètre de requête code que vous pouvez utiliser à l’étape suivante pour créer un jeton d’accès utilisateur. Si vous avez spécifié redirect_uri à l’étape précédente, cette URL de rappel est utilisée. Dans le cas contraire, la première URL de rappel de la page des paramètres de votre application est utilisée.

   Si vous avez spécifié le paramètre state à l’étape précédente, GitHub inclut également un paramètre state. Si le paramètre state ne correspond pas au paramètre state que vous avez envoyé à l’étape précédente, la demande ne peut pas être approuvée et le flux d’application web doit être abandonné.

3. Échangez le code de l’étape précédente contre un jeton d’accès utilisateur en effectuant une requête POST sur cette URL, avec les paramètres de requête suivants : http(s)://HOSTNAME/login/oauth/access_token

   Paramètre de requête.	Type	Description
   client_id	string	Obligatoire. ID client de votre GitHub App. ID client est différent de l’ID de l’application. Vous pouvez trouver votre ID client dans la page Paramètres de votre application. Pour plus d’informations sur la navigation vers la page des paramètres pour votre GitHub App, consultez « Modification d’une inscription d’application GitHub ».
   client_secret	string	Obligatoire. La clé secrète client de votre GitHub App. Vous pouvez générer une clé secrète client sur la page des paramètres de votre application.
   code	string	Obligatoire. Code que vous avez reçu à l’étape précédente.
   redirect_uri	string	URL de votre application où les utilisateurs sont redirigés après l’autorisation. Il doit s’agir d’une correspondance exacte avec l’une des URL que vous avez fournies en tant qu’« URL de rappel » lors de la configuration de votre GitHub App ; vous ne pouvez pas ajouter de paramètres supplémentaires.
   repository_id	string	ID d’un référentiel unique auquel le jeton d’accès utilisateur peut accéder. Si l’GitHub App ou l’utilisateur ne peuvent pas accéder au référentiel, cette action est ignorée. Utilisez ce paramètre pour restreindre davantage l’accès du jeton d’accès utilisateur.

4. GitHub envoie une réponse qui comprend les paramètres suivants :

   Paramètre de réponse	Type	Description
   access_token	string	Jeton d’accès utilisateur. Le jeton commence par ghu_.
   expires_in	integer	Nombre de secondes avant que n’expire access_token. Si vous avez désactivé l’expiration des jetons d’accès utilisateur, ce paramètre est omis. La valeur est toujours 28800 (8 heures).
   refresh_token	string	Le jeton d’actualisation. Si vous avez désactivé l’expiration des jetons d’accès utilisateur, ce paramètre est omis. Le jeton commence par ghr_.
   refresh_token_expires_in	integer	Nombre de secondes avant que n’expire refresh_token. Si vous avez désactivé l’expiration des jetons d’accès utilisateur, ce paramètre est omis. La valeur est toujours 15897600 (6 mois).
   scope	string	Étendues dont dispose le jeton. Cette valeur est toujours une chaîne vide. Contrairement à un jeton OAuth traditionnel, le jeton d’accès utilisateur est limité aux autorisations de votre application et de l’utilisateur.
   token_type	string	Type de jeton. La valeur est toujours bearer.

5. Utilisez le jeton d’accès utilisateur de l’étape précédente pour effectuer des demandes d’API au nom de l’utilisateur. Incluez le jeton d’accès utilisateur dans l’en-tête Authorization d’une demande d’API. Par exemple :

   curl --request GET \
   --url "http(s)://<em>HOSTNAME</em>/api/v3/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN"
   

Utilisation du flux d’appareil pour générer un jeton d’accès utilisateur

Si votre application est sans périphérique de contrôle ou n’a pas accès à un navigateur, vous devez utiliser le flux d’appareil pour générer un jeton d’accès utilisateur. Les outils CLI, les Raspberry Pi simples et les applications de bureau doivent par exemple utiliser le flux d’appareil. Pour obtenir un tutoriel qui utilise le flux d’appareil, consultez « Création d’une interface CLI avec une application GitHub App ».

Avant de pouvoir utiliser le flux d’appareil, vous devez d’abord l’activer dans les paramètres de votre application. Pour plus d’informations sur l’activation du flux d’appareil, consultez « Modification d’une inscription d’application GitHub ».

Le flux d’appareil utilise le type d’autorisation d’appareil OAuth 2.0.

1. Envoyez une requête POST à http(s)://HOSTNAME/login/device/code avec un paramètre de requête client_id. ID client est différent de l’ID de l’application. Vous pouvez trouver votre ID client dans la page Paramètres de votre application. Pour plus d’informations sur la navigation vers la page des paramètres pour votre GitHub App, consultez « Modification d’une inscription d’application GitHub ».

2. GitHub envoie une réponse qui comprend les paramètres de requête suivants :

   Paramètre de réponse	Type	Description
   device_code	string	Code de vérification qui sert à vérifier l’appareil. Ce code contient 40 caractères.
   user_code	string	Code de vérification que votre application doit afficher afin que l’utilisateur puisse entrer le code dans un navigateur. Il s’agit d’un code qui comporte 8 caractères avec un trait d’union au milieu. Par exemple : WDJB-MJHT.
   verification_uri	string	URL dans laquelle les utilisateurs doivent entrer leur user_code. L’URL est : http(s)://HOSTNAME/login/device.
   expires_in	integer	Nombre de secondes avant l’expiration de device_code et user_code. La valeur par défaut est 900 secondes (15 minutes).
   interval	integer	Nombre minimal de secondes qui doivent s’écouler avant que vous ne puissiez effectuer une nouvelle demande de jeton d’accès (POST http(s)://HOSTNAME/login/oauth/access_token) pour autoriser l’appareil. Si vous effectuez une requête avant la fin de cet intervalle de temps, vous atteignez la limite de débit et recevez une erreur slow_down. La valeur par défaut est 5 secondes.

3. Invitez l’utilisateur à entrer le user_code de l’étape précédente sur http(s)://HOSTNAME/login/device.

   Si l’utilisateur n’entre pas le code avant l’expiration du délai expires_in, le code n’est pas valide. Dans ce cas, vous devez redémarrer le flux d’appareil.

4. Interrogez POST http(s)://HOSTNAME/login/oauth/access_token avec les paramètres de requête client_id, device_code et grant_type (décrits ci-dessous) tant que les codes d’utilisateur et d’appareil n’ont pas expiré ou que l’utilisateur n’a pas autorisé l’application en entrant le user_code.

   Paramètre de requête.	Type	Description
   client_id	string	Obligatoire. ID client de votre GitHub App.
   device_code	string	Obligatoire. Code de vérification d’appareil que vous avez reçu à l’étape précédente.
   grant_type	string	Obligatoire. Le type d’autorisation doit être urn:ietf:params:oauth:grant-type:device_code.
   repository_id	string	ID d’un référentiel unique auquel le jeton d’accès utilisateur peut accéder. Si l’GitHub App ou l’utilisateur ne peuvent pas accéder au référentiel, cette action est ignorée. Utilisez ce paramètre pour restreindre davantage l’accès du jeton d’accès utilisateur.

   N’interrogez pas ce point de terminaison à une fréquence plus élevée que la fréquence indiquée par interval. Si vous le faites, vous atteignez la limite de débit et recevez une erreur slow_down. La réponse d’erreur slow_down ajoute 5 secondes au dernier interval.

   Tant que l’utilisateur n’a pas entré le code, GitHub répond avec un état 200 et un paramètre de requête de réponse error.

   Nom de l’erreur	Description
   authorization_pending	Cette erreur se produit quand la demande d’autorisation est en attente et que l’utilisateur n’a pas encore entré le code utilisateur. L’application est censée continuer à interroger le POST http(s)://HOSTNAME/login/oauth/access_token à une fréquence pas plus rapide que la fréquence spécifiée par interval.
   slow_down	Quand vous recevez l’erreur slow_down, 5 secondes supplémentaires sont ajoutées au interval ou au délai d’exécution minimal nécessaire entre vos requêtes à l’aide de POST http(s)://HOSTNAME/login/oauth/access_token. Par exemple, si l’intervalle de démarrage nécessite au moins 5 secondes entre les requêtes et que vous obtenez une erreur slow_down en réponse, vous devez attendre au moins 10 secondes avant d’effectuer une nouvelle requête pour un jeton. La réponse d’erreur inclut le nouveau interval à utiliser.
   expired_token	Si le code d’appareil a expiré, l’erreur token_expired s’affiche. Vous devez effectuer une nouvelle requête pour l’obtention d’un code d’appareil.
   unsupported_grant_type	Le type d’autorisation doit être urn:ietf:params:oauth:grant-type:device_code et doit être inclus en tant que paramètre d’entrée quand vous interrogez la demande de jeton OAuth POST http(s)://HOSTNAME/login/oauth/access_token.
   incorrect_client_credentials	Pour le flux d’appareil, vous devez passer l’ID client de votre application, que vous trouverez dans la page des paramètres de l’application. L’ID client est différent de l’ID d’application et du secret client.
   incorrect_device_code	Le device_code fourni n’est pas valide.
   access_denied	Quand un utilisateur clique sur Annuler pendant le processus d’autorisation, vous recevez une erreur access_denied, et l’utilisateur ne peut plus réutiliser le code de vérification.
   device_flow_disabled	Le flux d’appareil n’a pas été activé dans les paramètres de l’application. Pour plus d’informations sur l’activation du flux d’appareil, consultez « Modification d’une inscription d’application GitHub ».

5. Une fois que l’utilisateur a entré le user_code, GitHub donne une réponse qui contient les paramètres de requête suivants :

   Paramètre de réponse	Type	Description
   access_token	string	Jeton d’accès utilisateur. Le jeton commence par ghu_.
   expires_in	integer	Nombre de secondes avant que n’expire access_token. Si vous avez désactivé l’expiration des jetons d’accès utilisateur, ce paramètre est omis. La valeur est toujours 28800 (8 heures).
   refresh_token	string	Le jeton d’actualisation. Si vous avez désactivé l’expiration des jetons d’accès utilisateur, ce paramètre est omis. Le jeton commence par ghr_.
   refresh_token_expires_in	integer	Nombre de secondes avant que n’expire refresh_token. Si vous avez désactivé l’expiration des jetons d’accès utilisateur, ce paramètre est omis. La valeur est toujours 15897600 (6 mois).
   scope	string	Étendues dont dispose le jeton. Cette valeur est toujours une chaîne vide. Contrairement à un jeton OAuth traditionnel, le jeton d’accès utilisateur est limité aux autorisations de votre application et de l’utilisateur.
   token_type	string	Type de jeton. La valeur est toujours bearer.

6. Utilisez le jeton d’accès utilisateur de l’étape précédente pour effectuer des demandes d’API au nom de l’utilisateur. Incluez le jeton d’accès utilisateur dans l’en-tête Authorization d’une demande d’API. Par exemple :

   curl --request GET \
   --url "http(s)://<em>HOSTNAME</em>/api/v3/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN"
   

Génération d’un jeton d’accès utilisateur lorsqu’un utilisateur installe votre application

Si vous sélectionnez Demander l’autorisation utilisateur (OAuth) pendant l’installation dans les paramètres de votre application, GitHub démarre le flux d’application web immédiatement après l’installation de votre application par un utilisateur.

Vous pouvez générer un jeton d’accès utilisateur avec cette méthode, que l’application soit installée sur un compte d’utilisateur ou un compte d’organisation. Toutefois, si l’application a été installée sur un compte d’organisation, vous devez utiliser le flux d’application web ou le flux d’appareil pour générer un jeton d’accès utilisateur pour les autres utilisateurs de l’organisation.

1. Lorsqu’un utilisateur installe votre application, GitHub redirige l’utilisateur vers http(s)://HOSTNAME/login/oauth/authorize?client_id=CLIENT_ID, où CLIENT_ID est l’ID client de votre application.

2. Si l’utilisateur accepte votre demande d’autorisation, GitHub redirige l’utilisateur vers la première URL de rappel dans les paramètres de votre application et fournit un paramètre de requête code.

   Si vous souhaitez contrôler quelle URL de rappel est utilisée, ne sélectionnez pas Demander l’autorisation utilisateur (OAuth) pendant l’installation. Au lieu de cela, dirigez les utilisateurs via le flux d’application web complet et spécifiez le paramètre redirect_uri.

3. Échangez le code de l’étape précédente contre un jeton d’accès utilisateur en effectuant une requête POST sur cette URL, avec les paramètres de requête suivants : http(s)://HOSTNAME/login/oauth/access_token

   Paramètre de requête.	Type	Description
   client_id	string	Obligatoire. ID client de votre GitHub App. ID client est différent de l’ID de l’application. Vous pouvez trouver votre ID client dans la page Paramètres de votre application. Pour plus d’informations sur la navigation vers la page des paramètres pour votre GitHub App, consultez « Modification d’une inscription d’application GitHub ».
   client_secret	string	Obligatoire. La clé secrète client de votre GitHub App. Vous pouvez générer une clé secrète client sur la page des paramètres de votre application.
   code	string	Obligatoire. Code que vous avez reçu à l’étape précédente.
   redirect_uri	string	URL de votre application où les utilisateurs sont redirigés après l’autorisation. Il doit s’agir d’une correspondance exacte avec l’une des URL que vous avez fournies en tant qu’« URL de rappel » lors de la configuration de votre GitHub App ; vous ne pouvez pas ajouter de paramètres supplémentaires.
   repository_id	string	ID d’un référentiel unique auquel le jeton d’accès utilisateur peut accéder. Si l’GitHub App ou l’utilisateur ne peuvent pas accéder au référentiel, cette action est ignorée. Utilisez ce paramètre pour restreindre davantage l’accès du jeton d’accès utilisateur.

4. GitHub envoie une réponse qui comprend les paramètres suivants :

   Paramètre de réponse	Type	Description
   access_token	string	Jeton d’accès utilisateur. Le jeton commence par ghu_.
   expires_in	integer	Nombre de secondes avant que n’expire access_token. Si vous avez désactivé l’expiration des jetons d’accès utilisateur, ce paramètre est omis. La valeur est toujours 28800 (8 heures).
   refresh_token	string	Le jeton d’actualisation. Si vous avez désactivé l’expiration des jetons d’accès utilisateur, ce paramètre est omis. Le jeton commence par ghr_.
   refresh_token_expires_in	integer	Nombre de secondes avant que n’expire refresh_token. Si vous avez désactivé l’expiration des jetons d’accès utilisateur, ce paramètre est omis. La valeur est toujours 15897600 (6 mois).
   scope	string	Étendues dont dispose le jeton. Cette valeur est toujours une chaîne vide. Contrairement à un jeton OAuth traditionnel, le jeton d’accès utilisateur est limité aux autorisations de votre application et de l’utilisateur.
   token_type	string	Type de jeton. La valeur est toujours bearer.

5. Utilisez le jeton d’accès utilisateur de l’étape précédente pour effectuer des demandes d’API au nom de l’utilisateur. Incluez le jeton d’accès utilisateur dans l’en-tête Authorization d’une demande d’API. Par exemple :

   curl --request GET \
   --url "http(s)://<em>HOSTNAME</em>/api/v3/user" \
   --header "Accept: application/vnd.github+json" \
   --header "Authorization: Bearer USER_ACCESS_TOKEN"
   

Utilisation d’un jeton d’actualisation pour générer un jeton d’accès utilisateur

Par défaut, les jetons d’accès utilisateur expirent au bout de 8 heures. Si vous recevez un jeton d’accès utilisateur avec une expiration, vous recevrez également un jeton d’actualisation. Le jeton d’actualisation expire au bout de 6 mois. Vous pouvez utiliser ce jeton d’actualisation pour regénérer un jeton d’accès utilisateur. Pour plus d’informations, consultez « Actualisation des jetons d’accès utilisateur ».

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 ».

Dépannage

Les sections suivantes décrivent certaines erreurs que vous pouvez recevoir lors de la génération d’un jeton d’accès utilisateur.

Informations d’identification du client incorrectes

Si le client_id ou le client_secret que vous spécifiez sont incorrects, vous recevrez une erreur incorrect_client_credentials.

Pour résoudre cette erreur, vérifiez que vous utilisez les informations d’identification correctes pour votre GitHub App. Vous trouverez l’ID client et la clé secrète client dans la page des paramètres de votre GitHub App. Pour plus d’informations sur l’accès à la page des paramètres de votre GitHub App, consultez « Modification d’une inscription d’application GitHub ».

Incohérence d’URI de redirection

Si vous spécifiez un redirect_uri qui ne correspond pas à une des URL de rappel dans votre inscription GitHub App, vous recevrez une erreur redirect_uri_mismatch.

Pour résoudre cette erreur, fournissez un redirect_uri qui correspond à une des URL de rappel pour votre inscription GitHub App ou bien omettez ce paramètre pour utiliser par défaut la première URL de rappel qui est listée dans votre inscription GitHub App. Pour plus d’informations, consultez « À propos de l’URL de rappel d’autorisation utilisateur ».

Code de vérification erroné

Si vous utilisez un flux d’appareil et que le code de vérification (device_code) que vous avez spécifié est incorrect, a expiré ou ne correspond pas à la valeur que vous avez reçue de la demande initiale à http(s)://HOSTNAME/login/device/code, vous recevrez une erreur bad_verification_code.

Pour résoudre cette erreur, vous devez redémarrer le flux d’appareil pour obtenir un nouveau code. Pour plus d’informations, consultez « Utilisation du flux d’appareil pour générer un jeton d’accès utilisateur ».

Jeton d’actualisation incorrect

Si le jeton d’actualisation que vous avez spécifié n’est pas valide ou a expiré, vous recevrez une erreur bad_refresh_token.

Pour résoudre cette erreur, vous devez redémarrer le flux d’application web ou le flux d’appareil pour obtenir un nouveau jeton d’accès utilisateur et un nouveau jeton d’actualisation. Vous recevrez un jeton d’actualisation seulement si votre GitHub App a opté pour l’expiration des jetons d’accès utilisateur. Pour plus d’informations, consultez « Actualisation des jetons d’accès utilisateur ».

Type d’octroi non pris en charge

Quand vous demandez un jeton d’accès utilisateur via le flux d’appareil, le paramètre grant_type doit être urn:ietf:params:oauth:grant-type:device_code. Quand vous actualisez un jeton d’accès utilisateur en utilisant un jeton d’actualisation, le paramètre grant_type doit être refresh_token. Si vous n’utilisez pas le type d’octroi correct, vous recevrez une erreur unsupported_grant_type.

E-mail utilisateur non vérifié

Si l’utilisateur pour lequel vous essayez de générer un jeton d’accès utilisateur n’a pas confirmé son adresse e-mail principale auprès de GitHub, vous recevrez une erreur unverified_user_email.

Pour résoudre cette erreur, demandez à l’utilisateur de vérifier l’adresse e-mail principale sur son compte GitHub. Pour plus d’informations, consultez « Vérification de votre adresse e-mail » dans la documentation GitHub Free.