Skip to main content
Nous publions des mises à jour fréquentes de notre documentation, et la traduction de cette page peut encore être en cours. Pour obtenir les informations les plus actuelles, consultez la documentation anglaise.
All products
Applications

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

Dans cet article

Vous pouvez générer un jeton d’accès utilisateur pour votre GitHub App afin d’attribuer l’activité de l’application à un utilisateur.

À propos des jetons d’accès utilisateur

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

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 « installations d’application GitHub ».

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 « Best practices for creating a GitHub App ».

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 « Building a "Login with GitHub" button with a 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.TypeDescription
    client_idstringObligatoire. 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 les applications appartenant à l’utilisateur, la page Paramètres est https://github.com/settings/apps/APP-SLUG.

    Pour les applications appartenant à l’organisation, la page Paramètres est https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.

    Remplacez APP-SLUG par le nom slugifié de votre application et ORGANIZATION par le nom slugifié de votre organisation. Par exemple : https://github.com/organizations/octo-org/settings/apps/octo-app.
    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 comme « URL de rappel » dans les paramètres de votre application et ne peut pas contenir de paramètres supplémentaires.
    statestringLorsque 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.
    loginstringLorsqu’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_signupbooleanIndique 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.TypeDescription
    client_idstringObligatoire. 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 les applications appartenant à l’utilisateur, la page Paramètres est https://github.com/settings/apps/APP-SLUG.

    Pour les applications appartenant à l’organisation, la page Paramètres est https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.

    Remplacez APP-SLUG par le nom slugifié de votre application et ORGANIZATION par le nom slugifié de votre organisation. Par exemple : https://github.com/organizations/octo-org/settings/apps/octo-app.
    client_secretstringObligatoire. 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.
    codestringObligatoire. Code que vous avez reçu à l’étape précédente.
    redirect_uristringURL 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_idstringID 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éponseTypeDescription
    access_tokenstringJeton d’accès utilisateur. Le jeton commence par ghu_.
    expires_inintegerNombre 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_tokenstringLe 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_inintegerNombre 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 15811200 (6 mois).
    scopestringÉ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_typestringType 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)://HOSTNAME/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

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

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 « Building a CLI with a 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 « Modifying a GitHub App registration ».

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 les applications appartenant à l’utilisateur, la page Paramètres est https://github.com/settings/apps/APP-SLUG.
    • Pour les applications appartenant à l’organisation, la page Paramètres est https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.

    Remplacez APP-SLUG par le nom slugifié de votre application et ORGANIZATION par le nom slugifié de votre organisation. Par exemple : https://github.com/organizations/octo-org/settings/apps/octo-app.

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

    Paramètre de réponseTypeDescription
    device_codestringCode de vérification qui sert à vérifier l’appareil. Ce code contient 40 caractères.
    user_codestringCode 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_uristringURL dans laquelle les utilisateurs doivent entrer leur user_code. L’URL est : http(s)://HOSTNAME/login/device.
    expires_inintegerNombre de secondes avant l’expiration de device_code et user_code. La valeur par défaut est 900 secondes (15 minutes).
    intervalintegerNombre 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.TypeDescription
    client_idstringObligatoire. ID client de votre GitHub App.
    device_codestringObligatoire. Code de vérification d’appareil que vous avez reçu à l’étape précédente.
    grant_typestringObligatoire. Le type d’autorisation doit être urn:ietf:params:oauth:grant-type:device_code.
    repository_idstringID 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’erreurDescription
    authorization_pendingCette 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_downQuand 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_tokenSi 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_typeLe 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_credentialsPour 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_codeLe device_code fourni n’est pas valide.
    access_deniedQuand 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_disabledLe 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 « Modifying a GitHub App registration ».

  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éponseTypeDescription
    access_tokenstringJeton d’accès utilisateur. Le jeton commence par ghu_.
    expires_inintegerNombre 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_tokenstringLe 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_inintegerNombre 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 15811200 (6 mois).
    scopestringÉ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_typestringType 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)://HOSTNAME/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.TypeDescription
    client_idstringObligatoire. 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 les applications appartenant à l’utilisateur, la page Paramètres est https://github.com/settings/apps/APP-SLUG.

    Pour les applications appartenant à l’organisation, la page Paramètres est https://github.com/organizations/ORGANIZATION/settings/apps/APP-SLUG.

    Remplacez APP-SLUG par le nom slugifié de votre application et ORGANIZATION par le nom slugifié de votre organisation. Par exemple : https://github.com/organizations/octo-org/settings/apps/octo-app.
    client_secretstringObligatoire. 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.
    codestringObligatoire. Code que vous avez reçu à l’étape précédente.
    redirect_uristringURL 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_idstringID 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éponseTypeDescription
    access_tokenstringJeton d’accès utilisateur. Le jeton commence par ghu_.
    expires_inintegerNombre 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_tokenstringLe 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_inintegerNombre 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 15811200 (6 mois).
    scopestringÉ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_typestringType 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)://HOSTNAME/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 désactivé 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 ».

Points de terminaison pris en charge pour les jetons d’accès utilisateur

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

É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