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 : 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
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 :
- Les utilisateurs sont redirigés pour fournir leur identité GitHub
- Les utilisateurs sont redirigés vers votre site par GitHub
- 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
- 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.
- L’application invite l’utilisateur à entrer un code de vérification d’utilisateur dans
http(s)://HOSTNAME/login/device
. - 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.
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
- « 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 »