Validation de l'utilisateur secondaire

La validation utilisateur secondaire vous permet d'ajouter une sécurité à deux facteurs aux commandes vocales. Cela vous permet de 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, ce qui vous permet de décider quand Google Assistant doit relever un défi. Par exemple, vous pouvez choisir d'émettre une question d'authentification pour la caractéristique OnOff (Activer) pour une caméra de sécurité, mais pas pour la caractéristique OnOff (Règle d'activation) pour une lumière. Dans certaines situations, vous pouvez également rencontrer des problèmes Assistant pour la même action. Par exemple, vous pouvez demander à Assistant d'émettre 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 un défi si le porte-clés est présent.

Assistant peut émettre deux types de questions : la confirmation explicite ou le code secret. Un bloc de défi est ainsi ajouté aux QUERY et EXECUTE intents renvoyés de Assistant vers votre action, et accepte une réponse d'erreur challengeNeeded. Assistant renvoie ensuite la requête d'intent à votre action avec les données d'authentification dans le bloc d'authentification. Vous pouvez ensuite valider les données d'authentification pour déterminer si l'utilisateur a donné la bonne réponse de sécurité.

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

Types d'appareils compatibles

La validation des utilisateurs secondaires est compatible avec tous les types d'appareils.

Caractéristiques de l'appareil compatibles

La validation des utilisateurs secondaires est compatible avec toutes les caractéristiques des appareils.

Types de défis acceptés

Voici les types de tests secondaires acceptés pour la validation des utilisateurs:

• Aucun défi : requête et réponse qui n'utilisent pas de test de validation de l'utilisateur secondaire.
• ackNeeded : validation secondaire d'un utilisateur 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 d'authentification n'est pas recommandé pour les appareils et les caractéristiques de sécurité.
• pinNeeded : validation secondaire d'un utilisateur nécessitant un code secret, idéal pour les appareils et les caractéristiques de sécurité.

Aucun défi

Cet exemple présente une requête et une réponse EXECUTE réussies sans problème d'activation 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 pouvant utiliser plusieurs états pour une caractéristique ou une simple authentification de confirmation.

Voici les types de défis ackNeeded suivants:

• Simple nécessaire
• ackNeeded avec des états de caractéristiques

Élément ackNeeded simple

Cet exemple montre une requête simple et une réponse avec un défi ackNeeded de baisser la lumière, ainsi qu'une confirmation de la réduction de la lumière.

{
  "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 états de caractéristique

Une authentification de confirmation de l'utilisateur secondaire pouvant utiliser des états pour un trait. Par exemple, si vous travaillez avec la caractéristique TemperatureSetting et que thermostatMode et thermostatTemperatureSetpoint sont tous deux définis, Assistant peut demander à l'utilisateur Voulez-vous vraiment définir le chauffage de la climatisation sur 28 degrés ?

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

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

• ArmDisarm
• currentArmLevel
• currentStatusReport
• Remplir
• 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 mode de climatisation sur le chauffage et définit la température sur 28 degrés. Ensuite, Assistant demande aux utilisateurs l'autorisation d'allumer le chauffage et de définir la température sur 28 degrés, car un élément 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
      }
    }]
  }
}

Besoin d'un code

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. Assistant 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. Ce défi doit être utilisé après l'échec d'un premier défi pinNeeded.

Lorsqu'un type challengeFailedPinNeeded est renvoyé, Assistant 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 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 présente la requête et le code valide d'un code secret.

{
  "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 ont échoué. Veuillez accéder à l'application de votre appareil pour effectuer cette action.
• pinIncorrect - Malheureusement, le code de sécurité est incorrect.
• userCancelled - OK.

Consultez la liste complète des erreurs et exceptions.