Configurer Google Cloud et OAuth

L'accès à l'API Google Health est fourni via Google Cloud. Pour activer l'API et autoriser un compte Google, vous aurez besoin d'un projet Google Cloud.

Que vous soyez déjà un développeur d'API Fitbit ou que vous découvriez l'API Google Health API, vous devrez effectuer cette étape pour pouvoir appeler l'API.

Créer un projet et un client OAuth

Cliquez sur le bouton Activer l'API et obtenir un ID client OAuth 2.0 pour activer l'API Google Health et obtenir un ID client OAuth 2.0 :

  1. Si vous disposez déjà d'un projet Google Cloud que vous souhaitez utiliser pour l'API Google Health, assurez-vous d'abord d'être connecté au compte administrateur de ce projet. Sélectionnez ensuite le projet existant dans la liste des projets disponibles après avoir cliqué sur le bouton. Sinon, créez un projet.
  2. Sélectionnez Serveur Web lorsque vous êtes invité à indiquer d'où vous appelez.
  3. Saisissez https://www.google.com comme valeur pour URI de redirection autorisés. Un URI de redirection est requis pour obtenir un code d'autorisation à l'aide d'OAuth 2.0.
  4. Une fois la configuration terminée, copiez les valeurs de l'ID client OAuth 2.0 et du code secret du client, puis téléchargez le fichier JSON des identifiants sur votre machine locale.
Activer l'API et obtenir un ID client OAuth 2.0

Si vous souhaitez configurer manuellement votre projet Google Cloud ou vérifier la configuration et récupérer à nouveau vos identifiants :

  1. Activez l'API Google Health sur la page d'activation des API.
  2. Obtenez un ID client OAuth 2.0 sur la page des identifiants.

Pour en savoir plus sur la configuration d'OAuth 2.0 à l'aide de la console Google, consultez la page Utiliser le protocole OAuth 2.0 pour l'accès aux API Google.

Ajouter des utilisateurs tests

Par défaut, les clients OAuth nouvellement créés sont dans un état non validé et sont limités à 100 utilisateurs à des fins de test et de production. Pour activer l'autorisation pendant cette période, vous devez ajouter manuellement l'adresse e-mail de chaque utilisateur à la liste des utilisateurs tests dans la configuration de votre projet.

Mettez à jour la liste des utilisateurs tests sur la Audience page :

  1. Sur cette page, vous devriez voir l'"état de publication" défini sur Test, et le "type d'utilisateur" défini sur Externe.
  2. Dans la section "Utilisateurs tests", cliquez sur + Ajouter des utilisateurs. Saisissez l'adresse e-mail de tous les utilisateurs tests qui doivent être autorisés à accorder à votre application l'autorisation d'accéder à leurs données de santé.
  3. Cliquez sur Enregistrer.

Pour prendre en charge plus de 100 utilisateurs avec l'API Google Health, vous devez effectuer un examen de sécurité par un tiers. Pour en savoir plus, consultez le Centre d'aide sur la validation des applications OAuth.

Ajouter des niveaux d'accès

Vous devez spécifier les niveaux d'accès que votre client est autorisé à appeler sur la page "Accès aux données" :

  1. Sur cette page, cliquez sur Ajouter ou supprimer des niveaux d'accès.
  2. Dans la colonne "API", recherchez "API Google Health". Sélectionnez les niveaux d'accès dont vous avez besoin pour votre application.
  3. Une fois que vous avez sélectionné tous les niveaux d'accès dont vous avez besoin, cliquez sur Mettre à jour pour revenir à la page "Accès aux données".
  4. Cliquez sur Enregistrer.

Avant de sélectionner vos niveaux d'accès, consultez l' implémentation des niveaux d'accès.

Vous avez terminé de configurer votre ID client et devriez maintenant pouvoir appeler l'API Google Health.

Mettre à jour les niveaux d'accès

Vous pouvez inviter l'utilisateur à autoriser à nouveau votre application en définissant le paramètre `prompt` sur `consent` dans votre requête d'authentification. Lorsque prompt=consent est inclus, l'écran de consentement s'affiche chaque fois que votre application demande l'autorisation d'accéder à des niveaux d'accès, même si tous les niveaux d'accès ont déjà été accordés à votre projet Google APIs.

Pour ajouter ou modifier des niveaux d'accès à l'aide du paramètre prompt=consent, procédez comme suit :

  1. Identifiez la liste complète des niveaux d'accès dont votre application a besoin. Cela doit inclure les niveaux d'accès existants et tous les nouveaux niveaux d'accès que vous devez ajouter.

  2. Modifiez le paramètre `scope` dans l'URL d'autorisation pour inclure la liste mise à jour des valeurs de niveaux d'accès séparées par des espaces.

  3. Ajoutez prompt=consent à vos paramètres d'URI d'authentification. Cela force le serveur d'autorisation à demander le consentement de l'utilisateur avant de renvoyer des informations à votre client.

    L'exemple suivant montre une requête GET HTTPS au point de terminaison d'autorisation OAuth 2.0 de Google demandant plusieurs niveaux d'accès avec prompt=consent ajouté :

    https://accounts.google.com/o/oauth2/v2/auth?client_id=client-id&redirect_uri=redirect-uri&response_type=code&access_type=offline&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly%20https://www.googleapis.com/auth/googlehealth.sleep.readonly&prompt=consent

  4. Lorsque l'utilisateur suit le lien mis à jour, une page de consentement s'affiche, listant tous les niveaux d'accès demandés. Une fois que l'utilisateur a cliqué sur "Continuer" ou "Autoriser", vous recevrez un nouveau code d'autorisation qui pourra être échangé contre des jetons couvrant l'ensemble des niveaux d'accès.

    N'incluez prompt=consent que lorsque cela est nécessaire, par exemple lorsque vous devez obtenir un nouveau jeton d'actualisation ou lorsque les niveaux d'accès demandés ont changé.

Bibliothèques clientes OAuth2

La liste des bibliothèques clientes OAuth2 disponibles utilisées pour l'intégration aux frameworks courants est disponible sur la page Utiliser le protocole OAuth 2.0 pour l'accès aux API Google.

Jetons d'actualisation

Pour maintenir un accès à long terme aux API Google sans nécessiter une réauthentification constante de l'utilisateur, votre application doit utiliser un jeton d'actualisation. Pour obtenir des informations complètes sur l'implémentation, y compris les requêtes et paramètres HTTP spécifiques requis, consultez la documentation de la plate-forme d'identité Google.

Pour échanger un jeton d'actualisation contre un jeton d'accès, effectuez un appel HTTPS POST au point de terminaison de jeton OAuth 2.0 de Google. L'extrait de code suivant montre un exemple de requête et de réponse :

Requête

curl -L -X POST 'https://oauth2.googleapis.com/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'client_id=client-id&client_secret=client-secret&refresh_token=refresh-token&grant_type=refresh_token'

Réponse

{
  "access_token": "access-token",
  "expires_in": 3599,
  "scope": "scope-list",
  "token_type": "Bearer",
  "refresh_token": "refresh-token",
  "refresh_token_expires_in": 112154
}

Quand actualiser un jeton

Actualisez les jetons à la demande dans le cadre de la progression naturelle d'une session active d'un utilisateur lorsque les jetons d'accès ont expiré ou sont sur le point d'expirer. Évitez d'actualiser les jetons par lot (par exemple, en utilisant une tâche ou un service cron planifié pour actualiser les jetons de tous les utilisateurs à une heure fixe).

L'actualisation des jetons par lot n'est pas recommandée pour les raisons suivantes :

  • L'actualisation par lot empêche d'aligner les mises à jour des jetons sur les modèles de synchronisation des utilisateurs actifs. Bien que vous puissiez utiliser l' appel Get Devices pour afficher la dernière heure de synchronisation d'un utilisateur, cela nécessite un niveau d'accès OAuth supplémentaire que les utilisateurs ne sont pas obligés d'approuver.
  • Le traitement par lot met à jour les jetons qui n'ont pas besoin d'être actualisés, ce qui entraîne une surcharge de traitement redondante pour vos systèmes et les serveurs de Google.
  • Si un problème de réseau ou une panne de serveur se produit lors d'une actualisation par lot, tous les jetons d'utilisateur concernés sont affectés en même temps. L'actualisation individuelle des jetons lors de la progression naturelle des synchronisations des utilisateurs isole l'impact des échecs temporaires sur un seul utilisateur.
  • Le diagnostic des problèmes est plus difficile avec les tâches par lot. Étant donné que les requêtes par lot sont moins fréquentes et génèrent un grand nombre d'entrées de journal en même temps, il est plus difficile d'identifier le début d'un incident.
  • Les pics de concurrence élevés dans les requêtes de jetons lors des exécutions par lot augmentent le risque d'atteindre les limites de débit ou de rencontrer des erreurs d'authentification intermittentes.

Comportement des jetons lors des tests

Tenez compte du comportement des jetons d'actualisation en fonction de l'état de publication de votre projet Google Cloud :

  • Mode test : si votre écran de consentement OAuth est configuré avec un état de publication "Test", les jetons d'actualisation émis sont basés sur le temps et expirent au bout de sept jours. Pendant cette période, vous recevrez un seul jeton d'actualisation qui restera valide et utilisable pour obtenir de nouveaux jetons d'accès jusqu'à sa date d'expiration.
  • Mode publié : une fois que votre application est passée à l'état "En production", les jetons d'actualisation n'expirent généralement pas, sauf s'ils sont révoqués ou restent inutilisés pendant une période prolongée (généralement six mois).

Pour une expérience utilisateur fluide, assurez-vous de publier votre application avant de la déplacer dans un environnement de production afin d'éviter l'expiration des jetons au bout de 7 jours.

Protection multicompte (API RISC)

Activez le partage et la coordination des risques et des incidents (RISC) si vous souhaitez être informé des modifications apportées aux jetons d'événement ou à l'association de comptes, comme les comptes déconnectés ou les jetons révoqués, afin de nettoyer les jetons stockés et de mettre à jour l'état de connexion de l'interface utilisateur. L'activation de l'API RISC est facultative.

Pour activer l'API RISC pour votre projet Google Cloud :

  1. Ouvrez la page de l'API RISC dans la console Google Cloud. Assurez-vous que le projet que vous utilisez pour l'API Google Health est sélectionné.
  2. Lisez les conditions d'utilisation de RISC et assurez-vous de comprendre les exigences.
  3. Cliquez sur Activer si vous acceptez les conditions.

Après avoir activé l'API, vous devez créer et enregistrer un point de terminaison HTTPS pour recevoir et valider les jetons d'événement envoyés par Google.

Pour en savoir plus sur la protection multicompte et RISC, consultez Protéger les comptes utilisateur avec la protection multicompte.