Autorisation des applications OAuth

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 : permet d’accorder des autorisations aux utilisateurs pour les OAuth apps standard qui s’exécutent dans le navigateur. (Le type d’autorisation implicite n’est pas pris en charge.)
• flux d’appareil : utilisé pour les applications sans périphérique de contrôle, par exemple les outils CLI.

Flux d’application web

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.	Type	Requis ?	Description
client_id	string	Obligatoire	ID client que vous avez reçu de GitHub quand vous vous êtes inscrit.
redirect_uri	string	Fortement 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.
login	string	Facultatif	Suggère un compte spécifique à utiliser pour la connexion et l’autorisation de l’application.
scope	string	Dépendant du contexte	Liste 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.
state	string	Fortement recommandé	Chaîne aléatoire non modifiable. Elle est utilisée pour protéger contre les attaques de falsification de requête intersite.
allow_signup	string	Facultatif	Indique 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ètre	Type	Requis ?	Description
client_id	string	Obligatoire	ID client que vous avez reçu de GitHub Enterprise Server pour votre OAuth app.
client_secret	string	Requis	Secret client que vous avez reçu de GitHub Enterprise Server pour votre OAuth app.
code	string	Requis	Code que vous avez reçu en réponse à l’étape 1.
redirect_uri	string	Fortement 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ètre	Type	Description
client_id	string	Obligatoire. ID client que vous avez reçu de GitHub Enterprise Server pour votre application.
scope	string	Liste 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ètre	Type	Description
device_code	string	Le code de vérification d’appareil comporte 40 caractères et sert à vérifier l’appareil.
user_code	string	Le 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_uri	string	URL de vérification où les utilisateurs doivent entrer le user_code : 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 égale à 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. 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ètre	Type	Description
client_id	string	Obligatoire. ID client que vous avez reçu de GitHub Enterprise Server pour votre OAuth app.
device_code	string	Obligatoire. Le device_code que vous avez reçu de la demande POST http(s)://HOSTNAME/login/device/code.
grant_type	string	Obligatoire. 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'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 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_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 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_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. Le client_secret n’est pas nécessaire pour le flux d’appareil.
incorrect_device_code	Le device_code fourni n’est pas valide.
access_denied	Lorsqu’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_disabled	Le 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.

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

Dépannage

• « Résolution des problèmes de demande d’autorisation »
• « Résolution des erreurs de demande de jeton d’accès pour l’application OAuth »
• « Erreurs de flux d’appareils »
• « Expiration et révocation des jetons »

Pour aller plus loin

• « À propos de l’authentification auprès de GitHub »