Notice: We're retiring Works with Nest. See the home page for more information.
Google is committed to advancing racial equity for Black communities. See how.
Cette page a été traduite par l'API Cloud Translation.
Switch to English

Authentification et autorisation OAuth 2.0

L'API Nest utilise le protocole OAuth 2.0 pour l'authentification et l'autorisation.

Avant que votre produit puisse accéder aux données privées à l'aide de l'API Nest, il doit obtenir un jeton d'accès qui autorise l'accès à cette API. Un seul jeton d'accès peut accorder différents degrés d'accès à plusieurs sections de l'API.

La séquence d'autorisation commence lorsque votre produit redirige un navigateur vers une URL Nest avec des paramètres de requête indiquant l'accès demandé. Nest gère l'authentification de l'utilisateur, la sélection de session et le consentement de l'utilisateur. Le résultat est un code d'autorisation, que votre produit peut échanger contre un jeton d'accès. Votre produit peut ensuite utiliser le jeton d'accès pour passer des appels vers l'API Nest.

Flux OAuth 2.0
Flux OAuth 2.0

Configurez votre client Works with Nest

Pour trouver les informations d'identification OAuth 2.0 pour votre client, consultez l'onglet Présentation de la page client.

Rediriger l'URI ou l'autorisation basée sur un code PIN?

Lorsque vous configurez votre client, vous êtes invité à entrer un URI de redirection ou à laisser les champs URI de redirection vides pour utiliser l'autorisation basée sur un code PIN.

Si votre produit est un appareil qui n'a pas d'application ou de page Web associée (par exemple, un tracker de fitness, un appareil ou un panneau de sécurité), laissez les champs URI de redirection vides.

Si votre produit possède un composant de navigateur, la meilleure pratique consiste à inclure un URI de redirection.

Demander des autorisations

La configuration du client comprend un ensemble d'autorisations (également appelées étendues). Une autorisation est un paramètre variable qui contrôle l'ensemble des ressources et des opérations autorisées par un jeton d'accès. Il est généralement recommandé de demander des autorisations de manière incrémentielle, au moment où l'accès est requis, plutôt que d'avance.

Résultat

Lorsque vous enregistrez la configuration, votre client reçoit un ID client et un secret client uniques. De plus, votre client reçoit une URL d'autorisation.

L'URL d'autorisation comprend un paramètre d'état que vous pouvez utiliser pour tester d'éventuelles attaques de falsification de demandes intersites (CSRF). Voir Test des attaques CSRF .

Détails OAuth

Demander un code d'autorisation

Une fois votre client configuré, vous pouvez demander un code d'autorisation (parfois appelé code PIN). Le code d'autorisation n'est pas le dernier jeton que vous utilisez pour passer des appels vers Nest. Il est utilisé à l'étape suivante du flux OAuth 2.0 pour échanger contre un jeton d'accès réel. Cette étape fournit l'assurance directement de Nest à l'utilisateur que l'autorisation est accordée au produit approprié, avec l'accès convenu.

L'expérience utilisateur

Nous présentons une page Works with Nest qui demande à l'utilisateur d'accorder l'accès à votre produit. Cela identifie votre produit et décrit les autorisations utilisateur particulières (étendues) que votre produit a demandées. Les mots à l'écran proviennent de la configuration de votre client.

Pour tester cela vous-même, chargez l'URL d'autorisation de l'étape 1 dans un navigateur. Vous devriez voir une page de demande d'accès Works with Nest:

Fonctionne avec Nest

Allez-y et cliquez sur [ACCEPTER] vous-même pour voir ce que voit l'utilisateur. En cliquant sur le bouton [ACCEPTER], l'utilisateur approuve la demande de votre produit d'accéder à ses données.

Expérience PIN

Si vous laissez les champs URI de redirection vides dans la configuration de votre client, l'utilisateur est redirigé vers une page Nest qui affiche un code PIN (code d'autorisation). L'interface utilisateur de votre appareil devrait alors inviter l'utilisateur à entrer le code PIN manuellement.

Code PIN

Rediriger l'expérience URI

Si vous incluez un URI de redirection dans la configuration de votre client, l'utilisateur est redirigé vers une page de votre cloud (ou localhost) et Nest envoie automatiquement le code d'autorisation à l'appareil de l'utilisateur.

Test des attaques CSRF

Avant d'accepter le code d'autorisation, votre produit doit s'assurer que la valeur renvoyée dans le paramètre d'état correspond à la valeur d'état de votre demande d'autorisation d'origine. Cela garantit que vous avez affaire à l'utilisateur réel et non à un script malveillant. Si les valeurs d'état ne correspondent pas, vous devez lancer un code d'erreur HTTP 401 Unauthorized en réponse.

Une attaque CSRF est une attaque qui force un utilisateur final à exécuter des actions indésirables sur une application Web dans laquelle il est actuellement authentifié.

Attaque CSRF
Attaque CSRF

Pour éviter les attaques CSRF, nous vous recommandons de toujours soumettre un state obligatoire lors de la demande d'autorisation.

De cette façon, votre intégration Works with Nest peut vérifier que les codes d'accès obtenus à partir du cloud Nest répondent aux demandes faites par votre produit, et non par un autre produit.

Exemple:

Disons que dans votre configuration client, vous spécifiez l'URI de redirection:

 http://localhost:5000/callback
 

Supposons également que votre client envoie l'état 7tvPJiv8StrAqo9IQE9xsJaDso4 dans l'URL d'autorisation:

 https://home.nest.com/login/oauth2?client_id=CLIENT_ID&state=7tvPJiv8StrAqo9IQE9xsJaDso4
 

L'utilisateur consent à la demande.

Le cloud Nest renvoie le paramètre d'état dans le cadre de l'URI de redirection:

 127.0.0.1 - - [02/Jun/2017 13:18:58] "GET /callback?state=7tvPJiv8StrAqo9IQE9xsJaDso4&code=5N4CFK8E8TCFW7PM HTTP/1.1" 302 -
127.0.0.1 - - [02/Jun/2017 13:18:58] "GET / HTTP/1.1" 200 -
 

Votre produit reçoit cette valeur d'état et doit être programmé pour n'accepter que les redirections avec un état vérifiable.

Il existe plusieurs façons de générer un paramètre d'état non devinable. Vous pouvez fournir des valeurs d'état aléatoires à partir d'un dictionnaire conservé en mémoire ou d'une valeur recalculable. Vous pouvez utiliser une clé privée avec des variables facilement vérifiables (par exemple, l'ID client et un cookie de session) pour calculer une valeur hachée. Il en résulte une valeur d'octet difficile à deviner sans la clé privée. Une autre suggestion est de hacher la date et l'heure actuelles. Avec cette approche, votre application doit enregistrer l'heure de transmission pour la vérifier ou autoriser une période glissante de validité (par exemple, en utilisant l'algorithme de mot de passe à usage unique basé sur le temps [TOTP]).

Après avoir calculé le code d'authentification de message haché par clé (HMAC), l'encodez en base 64 et le transmettez au cloud Nest en tant que paramètre d'état.

Voici un exemple Python qui utilise datetime :

 import base64
import datetime
import hmac
import hashlib

def generate_state_parameter(client_id, private_key):
    date = datetime.datetime.today()
    raw_state = str(date) + client_id
    hashed = hmac.new(private_key, raw_state, hashlib.sha1)
    state = base64.b64encode(hashed.digest())
    return (state, date)
 

Messages d'erreur du code d'autorisation

Si la demande de code d'autorisation échoue, les utilisateurs voient un message d'erreur. Pour plus d'informations sur ces messages et comment les éviter, consultez la référence d'autorisation .

Échangez le code d'autorisation pour un jeton d'accès

La dernière étape de l'obtention d'un jeton d'accès consiste pour votre produit à en demander un en utilisant le code d'autorisation qu'il vient d'acquérir. Cela se fait en effectuant une requête HTTP POST "x-www-form-urlencoded".

Incluez les paramètres ci-dessous dans la demande. Les quatre paramètres sont obligatoires.

Paramètre La description
identité du client L'ID client à l'étape 1
client_secret Le secret du client à l'étape 1
code Le code d'autorisation reçu à l'étape 2
grant_type La valeur de ce champ doit toujours être: authorization_code

Avant chaque appel POST, obtenez un nouveau code d'autorisation. Pour ce faire, rechargez votre URL d'autorisation. Modifiez ensuite le paramètre de code POST pour inclure le nouveau code d'autorisation.

Exemples de code (auth)

Voir des exemples dans différentes langues .

Exemple de facteur (auth)

Postman fournit un moyen simple de tester les requêtes OAuth.

Dans l'onglet En- têtes , assurez-vous que Content-Type = application/x-www-form-urlencoded .

En-tête POST pour obtenir le jeton d'accès

Dans l'onglet Corps , incluez la clé suivante: paires de valeurs.

Corps POST pour obtenir le jeton d'accès

Réponse du jeton d'accès

Une requête réussie renvoie un objet JSON contenant les champs suivants:

  • access_token - Le jeton d'accès de l'utilisateur. Cette valeur doit être sécurisée.
  • expires_in - Le nombre de secondes restantes, à partir du moment où il a été demandé, avant l'expiration du jeton.

Messages d'erreur de jeton d'accès

Si la demande échoue, vous recevez une erreur sous la forme d'un code d'état HTTP. Pour plus d'informations sur ces erreurs et comment les éviter, consultez la référence d'autorisation .

Faire des demandes authentifiées

Une fois qu'un produit a obtenu un jeton d'accès, il envoie le jeton à une API Nest dans un en-tête d'autorisation HTTP. Il est possible d'envoyer des jetons en tant que paramètres de chaîne de requête URI, mais nous ne le recommandons pas, car les paramètres URI peuvent se retrouver dans des fichiers journaux qui ne sont pas complètement sécurisés.

Les jetons d'accès ne sont valides que pour l'ensemble des opérations et des ressources décrites dans la portée de la demande de jeton. Par exemple, si un jeton d'accès est émis pour l'API Nest Thermostat, il n'accorde pas l'accès à l'API Nest Camera.

Exemples de code (lecture / écriture)

Exemple de facteur (lecture / écriture)

Postman fournit un moyen simple de tester les appels d'API à l'aide de Content-Type = application/json .

OBTENIR de lire les données

Jetons non valides

Si vous effectuez un appel API à l'aide d'un jeton non valide, vous recevez une réponse 401 non autorisée du serveur. Un jeton peut être invalide et nécessiter une régénération car:

  • Il a expiré
  • L'utilisateur a révoqué l'autorisation qu'il avait initialement accordée à votre produit

Il est important que vous codiez votre produit pour gérer correctement une erreur 401 Unauthorized en redirigeant l'utilisateur vers le début du workflow d'autorisation.

Fonctionne avec la connexion Nest fermée

Si un utilisateur supprime une connexion Works with Nest , votre produit reçoit un événement auth_revoked et la connexion se ferme.