Initier un contrat d'API pour le modèle initiate+validate et initiate+wait

Modifier en ligne

La ressource initiate est lancée par des composants Verify internes lors d'une demande d'authentification MFA d'exécution quand le facteur utilisé prend en charge les modèles d'intégration "initiate+validate" ou "initiate+wait".

Par exemple, un smsotp ou une commande push. Verify s'attend à ce que la réponse contienne un status indiquant le succès ou l'échec du lancement MFA et un identificateur de transaction inclus dans les demandes "validate" ou "wait for result" ultérieures. L'exemple suivant illustre une requête type envoyée par Verify à la initiate ressource du webhook en temps réel. En fonction de la configuration du webhook, ce même contenu peut être envoyé directement au fournisseur MFA cible ou transformé en une demande de client d'API acceptable pour le fournisseur cible.
POST '/initiate' \
'Content-Type: application/json' \
'Accept: application/json' \

{
  "capability":  "<<factor capability name, e.g. totp>>",
  "id": "<<factor or device identifier from external provider>>",
  "attributes":
    {
      "username": "<<external MFA username>>"
    }
}
Remarque : l'URL /initiateHTTP indiquée dans cet exemple varie en fonction de la configuration du webhook.

Détails du lancement de la demande

Elément Descriptif
Demande HTTP POST
En-tête HTTP - Content-Type Le type de contenu du contenu de la demande est toujours application/json.
En-tête HTTP - Accept Le type de contenu attendu du contenu de la réponse est toujours application/json.
Contenu Objet JSON représentant la valeur de jeton ou de passe à valider. Le contenu identifie également l'utilisateur et son inscription ou enregistrement MFA associé.
id

Obligatoire. Identificateur unique de la fonction de facteur MFA inscrite ou enregistrée de l'utilisateur.
capability

Obligatoire. La valeur est une chaîne de caractères valide. Elle doit correspondre à l'une des fonctions qui sont configurées pour le fournisseur MFA associé au webhook.
attributes

Obligatoire. Attributs supplémentaires spécifiques à la demande.
attributes.username Obligatoire. Nom d'un utilisateur dans le système fournisseur externe pour lequel le lancement MFA est demandé.
L'exemple de code suivant est un exemple de contenu de réponse initiate.
{
    "attributes": {
        "<<any name>>": "<<any value>>"
    },
    "status": "SUCCESS",
    "transactionId": "<<provider transaction identifier>>"
}

Détails du lancement de la réponse

Eléments Descriptif
Type de contenu Objet JSON représentant le statut de la tentative de lancement MFA.
Code d'état HTTP Consultez l'état de l' HTTP.
status Obligatoire. Statut d'achèvement de la validation. Valeurs admises : SUCCESS, PENDING, TIMEOUT, CANCELED et FAILED
Remarque : renvoyer un statut deSUCCESSL'appel vers l'initié génère une erreur pour l'utilisateur final. « SUCCESS » n'est pas un statut valide pour l'appel Initiate

Si le fournisseur d'authentification multifactorielle prend en charge la nouvelle tentative de mot de passe à usage unique, le « statut » doit être « EN ATTENTE ».
transactionId

Obligatoire. Transaction ou autre descripteur d'état de la demande d'authentification du fournisseur MFA. Utilisé par le fournisseur pour établir une corrélation avec les appels "validate" (validation) ou "result poll" (interrogation des résultats) suivants.
attributes

Facultatif. Attributs supplémentaires renvoyés au client Verify public qui a déclenché la demande d'authentification MFA. Tous les attributs et valeurs peuvent être présents.