Skip to main content

Autorisation des applications OAuth

Vous pouvez autoriser d’autres utilisateurs à autoriser votre OAuth app.

Remarque : envisagez de créer une GitHub App à la place d’une OAuth app.

GitHub Apps et OAuth apps utilisent OAuth 2.0.

Les GitHub Apps peuvent agir pour le compte d’un utilisateur, comme une OAuth app ou comme elles-mêmes, ce qui est avantageux pour les automatisations qui ne nécessitent pas d’entrée utilisateur. En outre, les GitHub Apps utilisent des permissions affinées, offrent à l’utilisateur davantage de contrôle sur les référentiels auxquels l’application a accès et utilisent des jetons à courte durée de vie. Pour plus d’informations, consultez « Différences entre les applications GitHub et les applications OAuth » et « À propos de la création d’applications GitHub ».

L’implémentation d’OAuth de GitHub Enterprise Server 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 OAuth app, déterminez le flux d’autorisations 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 « Authentification auprès d’une application GitHub pour le compte d’un utilisateur ».

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 http(s)://HOSTNAME/login/oauth/authorize

Ce point de terminaison accepte les paramètres d’entrée suivants.

Paramètre de requête.TypeRequis ?Description
client_idstringObligatoireID client que vous avez reçu de GitHub quand vous vous êtes inscrit.
redirect_uristringFortement recommandéURL de votre application où les utilisateurs sont redirigés après l’autorisation. Consultez les détails ci-dessous sur les URL de redirection.
loginstringFacultatifSuggère un compte spécifique à utiliser pour la connexion et l’autorisation de l’application.
scopestringDépendant du contexteListe 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.
statestringFortement recommandéChaîne aléatoire non modifiable. Elle est utilisée pour protéger contre les attaques de falsification de requête intersite.
allow_signupstringFacultatifIndique 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.

Les paramètres PKCE (Proof Key for Code Exchange) code_challenge et code_challenge_method ne sont pas pris en charge pour l’instant. Les demandes de préversion CORS (OPTIONS) ne sont pas prises en charge pour l’instant.

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

Si l’utilisateur accepte votre requête, GitHub Enterprise Server 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 http(s)://HOSTNAME/login/oauth/access_token

Ce point de terminaison accepte les paramètres d’entrée suivants.

Nom du paramètreTypeRequis ?Description
client_idstringObligatoireID client que vous avez reçu de GitHub Enterprise Server pour votre OAuth app.
client_secretstringRequisSecret client que vous avez reçu de GitHub Enterprise Server pour votre OAuth app.
codestringRequisCode que vous avez reçu en réponse à l’étape 1.
redirect_uristringFortement recommandéURL de votre application où les utilisateurs sont redirigés après l’autorisation. Nous pouvons l’utiliser pour faire correspondre l’URI fourni à l’origine lorsque le code a été émis, afin d’empêcher les attaques contre votre service.

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

Chaque fois que vous recevez un jeton d’accès, vous devez l’utiliser pour revalider l’identité de l’utilisateur. Un utilisateur peut changer le compte auquel il est connecté lorsque vous lui demandez d’autoriser votre application, et vous risquez de mélanger les données de l’utilisateur si vous ne validez pas l’identité de l’utilisateur après chaque connexion.

Flux d’appareil

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 inscription d’application GitHub » pour GitHub Apps et « Modification d’une application OAuth » pour OAuth apps.

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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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.

Le point de terminaison accepte les paramètres d’entrée suivants.

Nom du paramètreTypeDescription
client_idstringObligatoire. ID client que vous avez reçu de GitHub Enterprise Server pour votre application.
scopestringListe séparée par des espaces des étendues auxquelles votre application demande l’accès. Pour plus d’informations, consultez « Étendues des applications OAuth ».

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%2FHOSTNAME%2Flogin%2Fdevice
Nom du paramètreTypeDescription
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 : http(s)://HOSTNAME/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 http(s)://HOSTNAME/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.

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": "http(s)://HOSTNAME/login/device",
  "expires_in": 900,
  "interval": 5
}
Accept: application/xml
<OAuth>
  <device_code>3584d83530557fdd1f46af8289938c8ef79f9dc5</device_code>
  <user_code>WDJB-MJHT</user_code>
  <verification_uri>http(s)://HOSTNAME/login/device</verification_uri>
  <expires_in>900</expires_in>
  <interval>5</interval>
</OAuth>

É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 http(s)://HOSTNAME/login/device.

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

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

Votre application effectue des demandes d’autorisation d’appareil qui interrogent POST http(s)://HOSTNAME/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 http(s)://HOSTNAME/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.

Le point de terminaison accepte les paramètres d’entrée suivants.

Nom du paramètreTypeDescription
client_idstringObligatoire. ID client que vous avez reçu de GitHub Enterprise Server pour votre OAuth app.
device_codestringObligatoire. Le device_code que vous avez reçu de la demande POST http(s)://HOSTNAME/login/device/code.
grant_typestringObligatoire. Le type d’autorisation doit être urn:ietf:params:oauth:grant-type:device_code.

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 http(s)://HOSTNAME/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 http(s)://HOSTNAME/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 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 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 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. Le client_secret n’est pas nécessaire pour le flux d’appareil.
incorrect_device_codeLe device_code fourni n’est pas valide.
access_deniedLorsqu’un utilisateur clique sur Annuler pendant le processus d’autorisation, vous recevez une erreur access_denied et l’utilisateur ne peut plus 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’appareils ».

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.

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 OAuth app. 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 redirect_uri facultatif peut également être utilisé pour les URL de bouclage, ce qui est utile pour les applications natives s’exécutant sur un ordinateur de bureau. 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 redirect_uri si votre application écoute sur le port 1234 :

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 OAuth apps

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 OAuth app 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 OAuth app 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 à OAuth app l’accès à ses référentiels privés.

Le nombre de jetons émis par combinaison utilisateur/application/étendue est limité à dix, avec une limite de taux de dix jetons créés par heure. 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. Toutefois, le fait d'atteindre la limite de débit horaire ne va pas révoquer votre jeton le plus ancien. Au lieu de cela, il déclenche une invite de ré-autorisation dans le navigateur, demandant à l’utilisateur de doubler vérifier les autorisations qu’il accorde à votre application. Cette invite est destinée à donner une pause à toute boucle infinie potentielle dans laquelle l’application est bloquée, car il n’y a pas de raison pour une application de demander dix jetons à l’utilisateur dans un délai d’une heure.

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 OAuth app pour que les utilisateurs puissent vérifier et révoquer leurs autorisations d’application.

Pour générer ce lien, vous avez besoin du client_id de votre OAuth app que vous avez reçu de GitHub au moment de l’inscription de l’application.

http(s)://HOSTNAME/settings/connections/applications/:client_id

Conseil :  pour en savoir plus sur les ressources auxquelles OAuth app a accès pour un utilisateur, consultez « Découverte de ressources pour un utilisateur ».

Dépannage

Pour aller plus loin