Validation de l'utilisateur secondaire

La validation d'utilisateur secondaire vous permet d'ajouter une sécurité à deux facteurs aux commandes vocales. Vous pouvez ainsi renforcer la sécurité de certaines actions, comme éteindre une caméra de sécurité ou ouvrir une porte. La validation de l'utilisateur secondaire n'est pas liée à une caractéristique d'appareil spécifique qui vous permet de décider quand demander à l'Assistant Google de lancer un défi. Par exemple, vous pouvez choisir d'émettre une question d'authentification pour la caractéristique OnOff (Activé) pour une caméra de sécurité, mais pas de lancer une question d'authentification pour la caractéristique OnOff (Activée) d'une lumière. Dans certaines situations, l'Assistant Google peut également lancer des défis pour la même action. Par exemple, vous pouvez demander à l'Assistant Google d'envoyer une demande d'authentification pour ouvrir une porte si un porte-clés NFC ne se trouve pas à proximité de cette porte, mais ne peut pas émettre de défi si le porte-clés est présent.

L'Assistant Google peut relever deux types de questions : la confirmation explicite ou le code secret. Cela ajoute un bloc d'authentification aux intents QUERY et EXECUTE renvoyés par l'Assistant Google à votre action, et accepte une réponse d'erreur challengeNeeded. L'Assistant Google renvoie ensuite la requête d'intent à votre action avec les données du défi dans le bloc "challenge". Vous pouvez ensuite valider les données du défi pour déterminer si l'utilisateur a donné la bonne réponse de sécurité.

L'Assistant Google utilise la boîte de dialogue pour lancer le défi, mais si vous l'utilisez sur des surfaces non vocales, le code et les confirmations sont affichés à l'écran.

Types d'appareils compatibles

La validation d'utilisateur secondaire est compatible avec tous les types d'appareils.

Caractéristiques des appareils compatibles

La validation d'utilisateur secondaire est compatible avec toutes les caractéristiques des appareils.

Types de questions d'authentification acceptés

Voici les types de questions d'authentification à la validation de l'utilisateur secondaires acceptés:

• Aucun défi : requête et réponse qui n'utilisent pas de question d'authentification pour la validation de l'utilisateur secondaire.
• ackNeeded : vérification d'utilisateur secondaire nécessitant un accusé de réception explicite (oui ou non) et pouvant également utiliser des états de caractéristiques comme commentaires de réponse. Ce type de défi n'est pas recommandé pour les appareils et les caractéristiques de sécurité.
• pinNeeded : validation secondaire de l'utilisateur nécessitant un code secret, idéal pour les appareils et les caractéristiques de sécurité.

Aucun défi

Cet exemple montre une requête EXECUTE réussie et une réponse sans problème d'allumage des lumières.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.OnOff",
          "params": {
            "on": true
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "on": true,
        "online": true
      }
    }]
  }
}

Confirmation nécessaire

Une authentification de confirmation de l'utilisateur secondaire qui peut utiliser plusieurs états pour une caractéristique ou une simple authentification de confirmation.

Il existe les types de types d'authentification ackNeeded suivants:

• Simple nécessaire
• ackNeeded avec état de caractéristique

Veuillez indiquer qu'il est nécessaire

Cet exemple montre une requête simple et une réponse avec un défi ackNeeded pour tamiser une lumière, ainsi que la confirmation de la réduction de la luminosité.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS"
    }]
  }
}

ackNeeded avec état de caractéristique

Une authentification de confirmation de l'utilisateur secondaire pouvant utiliser des états pour une caractéristique. Par exemple, si vous travaillez avec la caractéristique TempératureSetting, et que thermostatMode et thermostatTemperatureSetpoint sont tous les deux activés, l'Assistant Google peut demander à l'utilisateur Voulez-vous vraiment régler la température de la climatisation sur 28 degrés ?

Vous pouvez également inclure un état dans une réponse pour que l'Assistant Google effectue une action spécifique en fonction d'une requête donnée.

Les caractéristiques et les états suivants sont compatibles avec ackNeeded avec des états de caractéristiques. La liste d'un trait spécifique indique que tous ses états sont acceptés.

• ArmDisarm
• currentArmLevel
• currentStatusReport
• Remplissage
• LockUnlock
• Activé
• on
• OpenClose
• Scène
• TempératureSetting
• thermostatMode
• thermostatTemperatureSetpoint
• thermostatTemperatureSetpointHigh
• thermostatTemperatureSetpointLow

Cet exemple montre une requête et une réponse avec un défi ackNeeded qui utilise un état de caractéristique. Il règle le climatiseur sur le mode chauffage et définit la température sur 28 degrés. Ensuite, l'Assistant Google demande aux utilisateurs l'accusé de réception pour allumer le chauffage et régler la température sur 28 degrés, car un thermostatTemperatureSetpoint de 28 est renvoyé en tant qu'état dans la réponse.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      },
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "ackNeeded"
      }
    }]
  }
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.TemperatureSetting",
          "params": {
            "thermostatMode": "heat"
          },
          "challenge": {
            "ack": true
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "thermostatMode": "heat",
        "thermostatTemperatureSetpoint": 28
      }
    }]
  }
}

code requis

Le défi pinNeeded est recommandé pour les appareils de sécurité.

Cet exemple montre une requête initiale et une réponse avec un défi pinNeeded. L'exemple renvoie une réponse avec un défi pinNeeded. L'Assistant Google demande donc le code. À ce stade, l'utilisateur peut fournir un code incorrect ou valide.

Exemple de requête et de réponse pour un code incorrect ou valide:

• Code incorrect
• Code valide

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Code PIN incorrect.

Cet exemple montre la requête et la réponse avec un défi challengeFailedPinNeeded. Vous devez utiliser ce défi après l'échec d'un premier défi pinNeeded.

Lorsqu'un type challengeFailedPinNeeded est renvoyé, l'Assistant Google demande à nouveau le code de sécurité. Si l'utilisateur effectue trop de tentatives infructueuses, vous pouvez renvoyer une réponse d'erreur tooManyFailedAttempts. Consultez la section Réponses d'erreur.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333222"
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "challengeFailedPinNeeded"
      }
    }]
  }
}

Code valide

Cet exemple montre la requête et un code d'accès valide.

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.LockUnlock",
          "params": {
            "lock": false
          },
          "challenge": {
            "pin": "333444"
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "SUCCESS",
      "states": {
        "isLocked": false,
        "isJammed": false
      }
    }]
  }
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "inputs": [{
    "intent": "action.devices.EXECUTE",
    "payload": {
      "commands": [{
        "devices": [{
          "id": "123"
        }],
        "execution": [{
          "command": "action.devices.commands.BrightnessAbsolute",
          "params": {
            "brightness": 12
          }
        }]
      }]
    }
  }]
}

{
  "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
  "payload": {
    "commands": [{
      "ids": ["123"],
      "status": "ERROR",
      "errorCode": "challengeNeeded",
      "challengeNeeded": {
        "type": "pinNeeded"
      }
    }]
  }
}

Réponses d'erreur

Voici quelques codes d'erreur qui peuvent s'afficher avec vos réponses:

• challengeFailedNotSetup : Cette action nécessite un code de sécurité, mais elle n'a pas été configurée dans l'application de votre appareil.
• tooManyFailedAttempts - Désolé, un trop grand nombre de tentatives a échoué. Veuillez accéder à l'application de votre appareil pour effectuer cette action.
• pinIncorrect – Désolé, le code de sécurité est incorrect.
• userCancelled - OK

Consultez la liste complète des erreurs et exceptions.