OAuth 2.0 pour mobiles et applications 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 leurs Google Drive.

Les applications installées sont distribuées sur des appareils individuels, et on suppose qu'elles ne peuvent pas garder de secrets. Ils peuvent accéder aux API Google lorsque l'utilisateur est dans l'application ou lorsque celle-ci 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 du système et fournir un URI de redirection locale pour gérer les réponses du serveur d'autorisation de Google.

Alternatives

Pour les applications mobiles, vous pouvez utiliser Google Sign-In 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 à mettre en œuvre que le protocole de niveau inférieur décrit ici.

Pour les applications exécutées sur des appareils non compatibles avec un navigateur système ou dont les fonctionnalités d'entrée sont limitées, comme les téléviseurs, les consoles de jeu, 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 périphériques d'entrée limités.

Bibliothèques et exemples

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

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

Conditions préalables

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 Google API Console.
2. If prompted, select a project, or create a new one.
3. La liste 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 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 sur le 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 ci-dessous décrivent les types de clients et les méthodes de redirection compatibles avec le serveur d'autorisation de Google. Choisissez le type de client recommandé pour votre application, attribuez un nom à votre client OAuth et définissez les autres champs du formulaire selon vos besoins.

Identifier les niveaux d'accès

Les champs d'application permettent à votre application de ne demander l'accès qu'aux ressources dont elle a besoin, tout en permettant aux utilisateurs de contrôler le niveau d'accès qu'ils accordent à votre application. Ainsi, il peut y avoir 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 auxquels 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 afin d'obtenir le consentement d'un utilisateur pour effectuer une requête API en son nom. Votre application doit obtenir cette autorisation pour pouvoir exécuter une requête API Google nécessitant l'autorisation de l'utilisateur.

Étape 1: Générez un vérificateur de code et un défi

Google accepte le protocole PKCE (clé de vérification pour l'échange de code) afin de renforcer la sécurité du flux de l'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 l'outil de vérification du code

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

L'outil de vérification du code doit avoir suffisamment d'entropie pour qu'il soit difficile de deviner la valeur.

Créer le défi de code

Deux méthodes de création de 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 obligatoires response_type et client_id, ainsi que le paramètre facultatif state. Chaque URL contient des sauts de ligne et des espaces pour faciliter la lecture.

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 invite l'utilisateur à donner son consentement

Au cours de 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 des services d'API Google auxquels elle demande l'autorisation d'accéder, à l'aide des identifiants d'autorisation de l'utilisateur, ainsi qu'un résumé des champs d'application d'accès à accorder. Celui-ci peut alors accepter d'accorder l'accès à un ou plusieurs champs d'application demandés par votre application ou refuser la requête.

Votre application n'a rien à faire à ce stade, 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 contiendra 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",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

Appeler les API Google

Une fois que votre application a obtenu un jeton d'accès, vous pouvez l'utiliser pour appeler une API Google au nom d'un compte utilisateur donné, à condition que le ou les champs d'application requis par l'API aient été accordés. Pour ce faire, incluez le jeton d'accès dans une requête adressée à l'API en incluant un paramètre de requête access_token ou une valeur Bearer de l'en-tête HTTP Authorization. Dans la mesure du possible, il est préférable d'utiliser l'en-tête HTTP, 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 essayer toutes les API Google et consulter leur champ d'application sur OAuth 2.0 Playground.

Exemples HTTP GET

Un appel au point de terminaison drive.files (l'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 vers 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

Exemples curl

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 non valides pour une requête API associée. Vous pouvez actualiser un jeton d'accès sans demander l'autorisation de l'utilisateur (y compris en son absence) 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 HTTPS POST au serveur d'autorisation de Google (https://oauth2.googleapis.com/token) 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",
  "token_type": "Bearer"
}

Notez que le nombre de jetons d'actualisation qui seront é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 atteindre 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. L'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 à un site ou une application de la page "Applications et sites tiers ayant accès à votre compte" pour en savoir plus.

Une application peut également révoquer l'accès qui lui est accordé par programmation. La révocation programmatique est importante lorsqu'un utilisateur se désabonne ou supprime une application, ou lorsqu'elle a modifié les ressources d'API requises par une application. En d'autres termes, une partie du processus de suppression peut inclure une requête API pour garantir la suppression des autorisations précédemment accordées à l'application.

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 est associé à un jeton d'actualisation, le jeton d'actualisation est également révoqué.

Si la révocation est traitée correctement, le code d'état HTTP de la réponse est 200. En cas d'erreur, un code d'état HTTP 400 est renvoyé avec un code d'erreur.

Documentation complémentaire

La pratique actuelle de l'IETF (OAuth 2.0 pour les applications natives) établit un grand nombre des bonnes pratiques décrites ici.