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.

Autorisation des applications OAuth

Vous pouvez permettre à d’autres utilisateurs d’autoriser votre application OAuth.

L’implémentation d’OAuth de GitHub prend en charge les types d’autorisation standard suivants : l’autorisation via un code et l’autorisation d’appareil OAuth 2.0 destinée aux applications qui n’ont pas accès à un navigateur web.

Si vous souhaitez ignorer l’autorisation de votre application de manière standard, par exemple durant le test de votre application, vous pouvez utiliser le flux d’application non web.

Pour autoriser votre application OAuth, déterminez le flux d’autorisation qui correspond le mieux à votre application.

Flux d’application web

Remarque : Si vous créez une application GitHub, vous pouvez toujours utiliser le flux d’application web OAuth. Toutefois, la configuration présente certaines différences importantes. Pour plus d’informations, consultez « Identification et autorisation des utilisateurs pour les applications GitHub ».

Le flux d’application web permettant d’autoriser les utilisateurs pour votre application 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 accède à l’API avec le jeton d’accès de l’utilisateur

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

GET https://github.com/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_idstringRequis. ID client que vous avez reçu de GitHub quand vous vous êtes inscrit.
redirect_uristringURL de votre application où les utilisateurs sont redirigés après l’autorisation. Consultez les détails ci-dessous sur les URL de redirection.
loginstringSuggère un compte spécifique à utiliser pour la connexion et l’autorisation de l’application.
scopestringListe d’étendues délimitées par des espaces. En l’absence d’indication, la valeur par défaut de scope est une liste vide, si les utilisateurs n’ont autorisé aucune étendue pour l’application. Quand les utilisateurs disposent d’étendues d’autorisation pour l’application, ils ne voient pas s’afficher la page d’autorisation OAuth comportant la liste des étendues. À la place, cette étape du flux s’effectue automatiquement avec l’ensemble des étendues que l’utilisateur a autorisées pour l’application. Par exemple, si un utilisateur a déjà effectué le flux web à deux reprises et s’il a autorisé un jeton avec l’étendue user ainsi qu’un autre jeton avec l’étendue repo, un troisième flux web qui ne fournit pas de scope reçoit un jeton avec l’étendue user et l’étendue repo.
statestringChaîne aléatoire non modifiable. Elle est utilisée pour protéger contre les attaques de falsification de requête intersite.
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.

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

Si l’utilisateur accepte votre requête, GitHub est redirigé 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. Le code temporaire expire après 10 minutes. Si les états ne correspondent pas, un tiers créé la requête, et vous devez abandonner le processus.

Échangez ce code contre un jeton d’accès :

POST https://github.com/login/oauth/access_token

Paramètres

NomTypeDescription
client_idstringObligatoire. ID client que vous avez reçu de GitHub pour votre OAuth App.
client_secretstringObligatoire. Secret client que vous avez reçu de GitHub pour votre OAuth App.
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.

response

Par défaut, la réponse prend la forme suivante :

access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&scope=repo%2Cgist&token_type=bearer

Vous pouvez également recevoir la réponse dans différents formats, si vous indiquez le format souhaité dans l’en-tête Accept. Par exemple Accept: application/json ou Accept: application/xml :

Accept: application/json
{
  "access_token":"gho_16C7e42F292c6912E7710c838347Ae178B4a",
  "scope":"repo,gist",
  "token_type":"bearer"
}
Accept: application/xml
<OAuth>
  <token_type>bearer</token_type>
  <scope>repo,gist</scope>
  <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
</OAuth>

3. Utiliser le jeton d’accès pour accéder à l’API

Le jeton d’accès vous permet d’envoyer des requêtes à l’API au nom d’un utilisateur.

Authorization: Bearer OAUTH-TOKEN
GET https://api.github.com/user

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

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.github.com/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.

Avant de pouvoir utiliser le flux d’appareil pour autoriser et identifier des utilisateurs, vous devez d’abord l’activer dans les paramètres de votre application. Pour plus d’informations sur l’activation du flux d’appareil dans votre application, consultez « Modification d’une application OAuth » pour les applications OAuth, et « Modification d’une application GitHub » pour les applications GitHub.

Vue d’ensemble du flux d’appareil

  1. Votre application demande les codes de vérification d’appareil et d’utilisateur, puis obtient l’URL d’autorisation où l’utilisateur doit entrer le code de vérification d’utilisateur.
  2. L’application invite l’utilisateur à entrer un code de vérification d’utilisateur dans https://github.com/login/device.
  3. L’application interroge l’état de l’authentification de l’utilisateur. Une fois que l’utilisateur a autorisé l’appareil, l’application peut effectuer des appels d’API avec un nouveau jeton d’accès.

Étape 1 : L’application demande les codes de vérification d’appareil et d’utilisateur à GitHub

POST https://github.com/login/device/code

Votre application doit demander un code de vérification d’utilisateur et une URL de vérification. Tous deux permettront à l’application d’inviter l’utilisateur à s’authentifier à l’étape suivante. Cette requête retourne également un code de vérification d’appareil que l’application doit utiliser pour recevoir un jeton d’accès et vérifier l’état de l’authentification de l’utilisateur.

Paramètres d’entrée

NomTypeDescription
client_idstringObligatoire. ID client que vous avez reçu de GitHub pour votre application.
scopestringÉtendue à laquelle votre application demande l’accès.

response

Par défaut, la réponse prend la forme suivante :

device_code=3584d83530557fdd1f46af8289938c8ef79f9dc5&expires_in=900&interval=5&user_code=WDJB-MJHT&verification_uri=https%3A%2F%github.com%2Flogin%2Fdevice

Vous pouvez également recevoir la réponse dans différents formats, si vous indiquez le format souhaité dans l’en-tête Accept. Par exemple Accept: application/json ou Accept: application/xml :

Accept: application/json
{
  "device_code": "3584d83530557fdd1f46af8289938c8ef79f9dc5",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://github.com/login/device",
  "expires_in": 900,
  "interval": 5
}
Accept: application/xml
<OAuth>
  <device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code>
  <user_code>WDJB-MJHT</user_code>
  <verification_uri>https://github.com/login/device</verification_uri>
  <expires_in>900</expires_in>
  <interval>5</interval>
</OAuth>

Paramètres de réponse

NomTypeDescription
device_codestringLe code de vérification d’appareil comporte 40 caractères et sert à vérifier l’appareil.
user_codestringLe code de vérification d’utilisateur s’affiche sur l’appareil pour permettre à l’utilisateur d’entrer ce code dans un navigateur. Il s’agit d’un code qui comporte 8 caractères avec un trait d’union au milieu.
verification_uristringURL de vérification où les utilisateurs doivent entrer le user_code : https://github.com/login/device.
expires_inintegerNombre de secondes avant l’expiration de device_code et user_code. La valeur par défaut est égale à 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 https://github.com/login/oauth/access_token) pour autoriser l’appareil. Par exemple, si l’intervalle est égal à 5, vous ne pouvez pas effectuer de nouvelle requête avant 5 secondes. Si vous effectuez plusieurs requêtes en 5 secondes, vous atteignez la limite de débit et recevez une erreur slow_down.

Étape 2 : Inviter l’utilisateur à entrer le code utilisateur dans un navigateur

Votre appareil affiche le code de vérification d’utilisateur et invite l’utilisateur à entrer ce code dans https://github.com/login/device.

Champ permettant d’entrer le code de vérification de l’utilisateur affiché sur votre appareil

Étape 3 : L’application interroge GitHub pour vérifier si l’utilisateur a autorisé l’appareil

POST https://github.com/login/oauth/access_token

Votre application effectue des demandes d’autorisation d’appareil qui interrogent POST https://github.com/login/oauth/access_token, jusqu’à ce que les codes de vérification d’appareil et d’utilisateur expirent, ou jusqu’à ce que l’utilisateur parvienne à autoriser l’application avec un code utilisateur valide. L’application doit utiliser l’interrogation minimale interval récupérée à l’étape 1 pour éviter les erreurs de limite de débit. Pour plus d’informations, consultez « Limites de débit pour le flux d’appareil ».

L’utilisateur doit entrer un code valide dans un délai de 15 minutes (ou 900 secondes). Après 15 minutes, vous devez demander un nouveau code d’autorisation d’appareil avec POST https://github.com/login/device/code.

Une fois que l’utilisateur a effectué l’autorisation, l’application reçoit un jeton d’accès qui permet d’envoyer des requêtes à l’API au nom d’un utilisateur.

Paramètres d'entrée

NomTypeDescription
client_idstringObligatoire. ID client que vous avez reçu de GitHub pour votre OAuth App.
device_codestringObligatoire. Code de vérification d’appareil que vous avez reçu à la suite de la requête POST https://github.com/login/device/code.
grant_typestringObligatoire. Le type d’autorisation doit être urn:ietf:params:oauth:grant-type:device_code.

response

Par défaut, la réponse prend la forme suivante :

access_token=gho_16C7e42F292c6912E7710c838347Ae178B4a&token_type=bearer&scope=repo%2Cgist

Vous pouvez également recevoir la réponse dans différents formats, si vous indiquez le format souhaité dans l’en-tête Accept. Par exemple Accept: application/json ou Accept: application/xml :

Accept: application/json
{
 "access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
  "token_type": "bearer",
  "scope": "repo,gist"
}
Accept: application/xml
<OAuth>
  <access_token>gho_16C7e42F292c6912E7710c838347Ae178B4a</access_token>
  <token_type>bearer</token_type>
  <scope>gist,repo</scope>
</OAuth>

Limites de débit pour le flux d’appareil

Quand un utilisateur envoie le code de vérification dans le navigateur, le débit est limité à 50 envois par heure et par application.

Si vous effectuez plusieurs demandes de jeton d’accès (POST https://github.com/login/oauth/access_token) sans respecter le délai d’exécution minimal nécessaire entre les demandes (ou interval), vous atteignez la limite de débit et recevez une réponse d’erreur slow_down. La réponse d’erreur slow_down ajoute 5 secondes au dernier interval. Pour plus d’informations, consultez les codes d’erreurs du flux d’appareil.

Codes d’erreur du flux d’appareil

Code d'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 doit continuer à interroger la requête POST https://github.com/login/oauth/access_token sans dépasser la valeur de interval, ce qui nécessite un nombre minimal de secondes entre chaque requête.
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 https://github.com/login/oauth/access_token. Par exemple, si l’intervalle de démarrage nécessite au moins 5 secondes entre les requêtes et si vous obtenez une réponse d’erreur slow_down, vous devez attendre au moins 10 secondes avant d’effectuer une nouvelle requête pour un jeton d’accès OAuth. 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 https://github.com/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. Le client_secret n’est pas nécessaire pour le flux d’appareil.
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, consultez « Flux d’appareil ».

Pour plus d’informations, consultez « Type d’autorisation d’appareil OAuth 2.0 ».

Flux d’application non-web

L’authentification non-web est disponible pour des situations limitées, par exemple les tests. Si nécessaire, vous pouvez utiliser l’authentification de base pour créer un personal access token en utilisant la page de paramètres des personal access tokens. Cette technique permet à l’utilisateur de révoquer l’accès à tout moment.

Remarque : Quand vous utilisez le flux d’application non-web pour créer un jeton OAuth2, veillez à bien comprendre le fonctionnement de l’authentification à 2 facteurs, si celle-ci est activée pour vous ou vos utilisateurs.

URL de redirection

Le paramètre redirect_uri est facultatif. S’il est omis, GitHub redirige les utilisateurs vers l’URL de rappel configurée dans les paramètres d’application OAuth. S’il est fourni, l’hôte (à l’exclusion des sous-domaines) et le port de l’URL de redirection doivent correspondre exactement à l’URL de rappel. Le chemin de l’URL de redirection doit référencer un sous-répertoire de l’URL de rappel.

CALLBACK: http://example.com/path

GOOD: http://example.com/path
GOOD: http://example.com/path/subdir/other
GOOD: http://oauth.example.com/path
GOOD: http://oauth.example.com/path/subdir/other
BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org

URL de redirection de bouclage

Le paramètre facultatif redirect_uri peut également être utilisé pour les URL de bouclage. Si l’application spécifie une URL de bouclage et un port, une fois l’application autorisée, les utilisateurs sont redirigés vers l’URL et le port fournis. redirect_uri n’a pas besoin de correspondre au port spécifié dans l’URL de rappel pour l’application.

Pour l’URL de rappel http://127.0.0.1/path, vous pouvez utiliser ce redirect_uri :

http://127.0.0.1:1234/path

Notez qu’OAuth RFC recommande de ne pas utiliser localhost, mais d’utiliser à la place le littéral de bouclage 127.0.0.1 ou l’adresse IPv6 ::1.

Création de plusieurs jetons pour les applications OAuth

Vous pouvez créer plusieurs jetons pour une combinaison utilisateur/application/étendue en réponse à des cas d’usage spécifiques.

Cela est utile si votre application OAuth prend en charge un workflow qui utilise GitHub pour la connexion et nécessite uniquement des informations utilisateur de base. Un autre workflow peut nécessiter l’accès aux dépôts privés d’un utilisateur. Avec plusieurs jetons, votre application OAuth peut effectuer le flux web pour chaque cas d’usage, en demandant uniquement les étendues nécessaires. Si un utilisateur se sert de votre application uniquement pour se connecter, il n’est jamais tenu d’octroyer à l’application OAuth l’accès à ses dépôts privés.

Il existe une limite de dix jetons émis par combinaison utilisateur/application/étendue. Si une application crée plus de 10 jetons pour le même utilisateur et les mêmes étendues, les jetons les plus anciens avec la même combinaison utilisateur/application/étendue seront révoqués.

Avertissement : La révocation de toutes les autorisations d’une OAuth App supprime toutes les clés SSH générées au nom de l’utilisateur par l’application, y compris les clés de déploiement.

Redirection des utilisateurs pour la vérification de leur accès

Vous pouvez créer un lien vers les informations d’autorisation d’une application OAuth pour que les utilisateurs puissent vérifier et révoquer leurs autorisations d’application.

Pour créer ce lien, vous avez besoin du client_id d’application OAuth que vous avez reçu de GitHub au moment de l’inscription de l’application.

https://github.com/settings/connections/applications/:client_id

Conseil : Pour en savoir plus sur les ressources auxquelles un utilisateur a accès via votre application OAuth, consultez « Découverte des ressources pour un utilisateur ».

Dépannage

Pour aller plus loin