OAuth 2.0 pour les applications mobiles et de bureau

Ce document explique comment les applications installées sur des appareils tels que des téléphones, des tablettes et des ordinateurs utilisent les points de terminaison OAuth 2.0 de Google pour autoriser l'accès aux API Google.

OAuth 2.0 permet aux utilisateurs de partager des données spécifiques avec une application tout en préservant la confidentialité de leurs noms d'utilisateur, mots de passe et autres informations. Par exemple, une application peut utiliser OAuth 2.0 pour obtenir l'autorisation des utilisateurs de stocker des fichiers dans leur Google Drive.

Les applications installées sont distribuées à des appareils individuels, et on suppose qu'elles ne peuvent pas garder de secrets. Elles peuvent accéder aux API Google lorsque l'utilisateur est présent dans l'application ou lorsque l'application s'exécute en arrière-plan.

Ce flux d'autorisation est semblable à celui utilisé pour les applications de serveur Web. La principale différence est que les applications installées doivent ouvrir le navigateur système et fournir un URI de redirection local pour gérer les réponses du serveur d'autorisation de Google.

Alternatives

Pour les applications mobiles, vous pouvez préférer utiliser la fonctionnalité de connexion Google pour Android ou iOS. Les biblioth��ques clientes Google Sign-In gèrent l'authentification et l'autorisation des utilisateurs. Elles peuvent être plus simples à implémenter que le protocole de niveau inférieur décrit ici.

Pour les applications exécutées sur des appareils qui ne prennent pas en charge de navigateur système ou qui disposent de fonctionnalités d'entrée limitées, comme les téléviseurs, les consoles de jeux, les appareils photo ou les imprimantes, consultez OAuth 2.0 pour les téléviseurs et les appareils ou Connexion sur les téléviseurs et les appareils à entrée limitée.

Bibliothèques et exemples

Nous vous recommandons d'utiliser les bibliothèques et exemples suivants pour vous aider à implémenter le flux OAuth 2.0 décrit dans ce document:

• Bibliothèque AppAuth for Android
• Bibliothèque AppAuth pour iOS
• OAuth pour les applications: exemples Windows

Prérequis

Activer les API pour votre projet.

Toute application qui appelle des API Google doit les activer dans API Console.

Pour activer une API pour votre projet:

1. Open the API Library dans le Google API Console.
2. If prompted, select a project, or create a new one.
3. API Library répertorie toutes les API disponibles, regroupées par famille de produits et par popularité. Si l'API que vous souhaitez activer n'apparaît pas dans la liste, utilisez la fonctionnalité de recherche pour la trouver ou cliquez sur Tout afficher dans la famille de produits à laquelle elle appartient.
4. Sélectionnez l'API que vous souhaitez activer, puis cliquez sur le bouton Activer.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

Créer des identifiants d'autorisation

Toute application qui utilise OAuth 2.0 pour accéder aux API Google doit disposer d'identifiants d'autorisation qui identifient l'application auprès du serveur OAuth 2.0 de Google. Les étapes suivantes expliquent comment créer des identifiants pour votre projet. Vos applications peuvent ensuite utiliser les identifiants pour accéder aux API que vous avez activées pour ce projet.

1. Go to the Credentials page.
2. Cliquez sur Créer des identifiants > ID client OAuth.
3. Les sections suivantes décrivent les types de clients compatibles avec le serveur d'autorisation de Google. Choisissez le type de client recommandé pour votre application, nommez votre client OAuth et définissez les autres champs du formulaire selon les besoins.

Identifier les niveaux d'accès

Les champs d'application permettent à votre application de demander uniquement l'accès aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler le nombre d'accès qu'ils accordent à votre application. Par conséquent, il peut exister une relation inverse entre le nombre de champs d'application demandés et la probabilité d'obtenir le consentement de l'utilisateur.

Avant de commencer à implémenter l'autorisation OAuth 2.0, nous vous recommandons d'identifier les champs d'application pour lesquels votre application aura besoin d'une autorisation d'accès.

Le document Champs d'application des API OAuth 2.0 contient la liste complète des champs d'application que vous pouvez utiliser pour accéder aux API Google.

Obtenir des jetons d'accès OAuth 2.0

Les étapes suivantes montrent comment votre application interagit avec le serveur OAuth 2.0 de Google pour obtenir le consentement d'un utilisateur afin d'effectuer une requête API en son nom. Votre application doit disposer de ce consentement avant de pouvoir exécuter une requête d'API Google nécessitant l'autorisation de l'utilisateur.

Étape 1: Générer un code de validation et un défi

Google est compatible avec le protocole Proof Key for Code Exchange (PKCE) pour renforcer la sécurité du flux d'application installée. Un vérificateur de code unique est créé pour chaque requête d'autorisation, et sa valeur transformée, appelée "code_challenge", est envoyée au serveur d'autorisation pour obtenir le code d'autorisation.

Créer le vérificateur de code

Un code_verifier est une chaîne aléatoire cryptographique à haute entropie qui utilise les caractères non réservés [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", avec une longueur minimale de 43 caractères et une longueur maximale de 128 caractères.

Le vérificateur de code doit avoir un degré d'entropie suffisant pour rendre la valeur impossible à deviner.

Créer le défi de programmation

Deux méthodes de création du défi de code sont acceptées.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

Étape 2: Envoyer une requête au serveur OAuth 2.0 de Google

Pour obtenir l'autorisation de l'utilisateur, envoyez une requête au serveur d'autorisation de Google à l'adresse https://accounts.google.com/o/oauth2/v2/auth. Ce point de terminaison gère la recherche de session active, authentifie l'utilisateur et obtient son consentement. Le point de terminaison n'est accessible que via SSL et refuse les connexions HTTP (non SSL).

Le serveur d'autorisation accepte les paramètres de chaîne de requête suivants pour les applications installées:

Exemples d'URL d'autorisation

Les onglets ci-dessous présentent des exemples d'URL d'autorisation pour les différentes options d'URI de redirection.

Les URL sont identiques, à l'exception de la valeur du paramètre redirect_uri. Les URL contiennent également les paramètres response_type et client_id obligatoires, ainsi que le paramètre state facultatif. Chaque URL contient des sauts de ligne et des espaces pour une meilleure lisibilité.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Étape 3: Google demande à l'utilisateur son consentement

À cette étape, l'utilisateur décide d'accorder ou non l'accès demandé à votre application. À ce stade, Google affiche une fenêtre de consentement indiquant le nom de votre application et les services de l'API Google auxquels il demande l'autorisation d'accéder à l'aide des identifiants de l'utilisateur, ainsi qu'un récapitulatif des niveaux d'accès à accorder. L'utilisateur peut alors accepter d'accorder l'accès à un ou plusieurs champs d'application demandés par votre application ou refuser la requête.

À ce stade, votre application n'a rien à faire, car elle attend la réponse du serveur OAuth 2.0 de Google indiquant si un accès a été accordé. Cette réponse est expliquée à l'étape suivante.

Étape 4: Gérer la réponse du serveur OAuth 2.0

La manière dont votre application reçoit la réponse d'autorisation dépend du schéma d'URI de redirection qu'elle utilise. Quel que soit le schéma, la réponse contient un code d'autorisation (code) ou une erreur (error). Par exemple, error=access_denied indique que l'utilisateur a refusé la requête.

Si l'utilisateur accorde l'accès à votre application, vous pouvez échanger le code d'autorisation contre un jeton d'accès et un jeton d'actualisation, comme décrit à l'étape suivante.

Étape 5: Échangez le code d'autorisation contre des jetons d'actualisation et d'accès

Pour échanger un code d'autorisation contre un jeton d'accès, appelez le point de terminaison https://oauth2.googleapis.com/token et définissez les paramètres suivants:

L'extrait de code suivant présente un exemple de requête:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

Google répond à cette requête en renvoyant un objet JSON contenant un jeton d'accès de courte durée et un jeton d'actualisation.

La réponse contient les champs suivants :

L'extrait de code suivant montre un exemple de réponse:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Étape 6: Vérifiez les autorisations accordées par les utilisateurs

Lorsque vous demandez plusieurs niveaux d'accès à la fois, les utilisateurs peuvent ne pas accorder tous les niveaux d'accès demandés par votre application. Votre application doit toujours vérifier les autorisations accordées par l'utilisateur et gérer tout refus d'autorisation en désactivant les fonctionnalités concernées. Pour en savoir plus, consultez Gérer les autorisations précises.

Pour vérifier si l'utilisateur a accordé à votre application l'accès à un champ d'application particulier, examinez le champ scope dans la réponse du jeton d'accès. Champs d'application d'accès accordés par le jeton d'accès, exprimés sous la forme d'une liste de chaînes sensibles à la casse, délimitées par des espaces.

Par exemple, l'exemple de réponse du jeton d'accès suivant indique que l'utilisateur a accordé à votre application l'accès aux autorisations d'activité Drive en lecture seule et aux événements Agenda:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

Appeler des API Google

Une fois que votre application a obtenu un jeton d'accès, vous pouvez l'utiliser pour effectuer des appels à une API Google au nom d'un compte utilisateur donné si le ou les champs d'application de l'accès requis par l'API ont été accordés. Pour ce faire, incluez le jeton d'accès dans une requête envoyée à l'API en incluant un paramètre de requête access_token ou une valeur Bearer d'en-tête HTTP Authorization. Lorsque c'est possible, l'en-tête HTTP est préférable, car les chaînes de requête ont tendance à être visibles dans les journaux du serveur. Dans la plupart des cas, vous pouvez utiliser une bibliothèque cliente pour configurer vos appels aux API Google (par exemple, lorsque vous appelez l'API Drive Files).

Vous pouvez tester toutes les API Google et consulter leurs champs d'application sur OAuth 2.0 Playground.

Exemples de requêtes HTTP GET

Un appel au point de terminaison drive.files (API Drive Files) à l'aide de l'en-tête HTTP Authorization: Bearer peut se présenter comme suit. Notez que vous devez spécifier votre propre jeton d'accès:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Voici un appel à la même API pour l'utilisateur authentifié à l'aide du paramètre de chaîne de requête access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl exemples

Vous pouvez tester ces commandes avec l'application de ligne de commande curl. Voici un exemple qui utilise l'option d'en-tête HTTP (recommandée):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Vous pouvez également utiliser l'option de paramètre de chaîne de requête:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Actualiser un jeton d'accès

Les jetons d'accès expirent régulièrement et deviennent des identifiants non valides pour une requête API associée. Vous pouvez actualiser un jeton d'accès sans demander l'autorisation à l'utilisateur (y compris lorsqu'il n'est pas présent) si vous avez demandé un accès hors connexion aux champs d'application associés au jeton.

Pour actualiser un jeton d'accès, votre application envoie une requête POST HTTPS au serveur d'autorisation (https://oauth2.googleapis.com/token) de Google, qui inclut les paramètres suivants:

L'extrait de code suivant présente un exemple de requête:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Tant que l'utilisateur n'a pas révoqué l'accès accordé à l'application, le serveur de jetons renvoie un objet JSON contenant un nouveau jeton d'accès. L'extrait de code suivant montre un exemple de réponse:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

Notez que le nombre de jetons d'actualisation émis est limité : une limite par combinaison client/utilisateur et une autre par utilisateur pour tous les clients. Vous devez enregistrer les jetons d'actualisation dans un espace de stockage à long terme et continuer à les utiliser tant qu'ils restent valides. Si votre application demande trop de jetons d'actualisation, elle peut rencontrer ces limites, auquel cas les jetons d'actualisation plus anciens cesseront de fonctionner.

Révoquer un jeton

Dans certains cas, un utilisateur peut souhaiter révoquer l'accès accordé à une application. Un utilisateur peut révoquer l'accès en accédant aux paramètres du compte. Pour en savoir plus, consultez la section Supprimer l'accès d'une application ou d'un site du document d'aide "Applications et sites tiers ayant accès à votre compte".

Une application peut également révoquer de manière programmatique l'accès qui lui a été accordé. La révocation programmatique est importante dans les cas où un utilisateur se désinscrit, supprime une application ou que les ressources d'API requises par une application ont changé de manière significative. En d'autres termes, une partie du processus de suppression peut inclure une requête d'API pour s'assurer que les autorisations précédemment accordées à l'application sont supprimées.

Pour révoquer un jeton de manière programmatique, votre application envoie une requête à https://oauth2.googleapis.com/revoke et inclut le jeton en tant que paramètre:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Il peut s'agir d'un jeton d'accès ou d'un jeton d'actualisation. Si le jeton est un jeton d'accès et qu'il dispose d'un jeton d'actualisation correspondant, le jeton d'actualisation est également révoqué.

Si la révocation est traitée avec succès, le code d'état HTTP de la réponse est 200. Pour les conditions d'erreur, un code d'état HTTP 400 est renvoyé avec un code d'erreur.

Méthodes de redirection d'application

Protéger vos applications

Documentation complémentaire

Les bonnes pratiques actuelles de l'IETF OAuth 2.0 pour les applications natives établissent bon nombre des bonnes pratiques décrites ici.