API-Vertrag für initiate+validate- und initiate+wait-Muster einleiten

Online bearbeiten

Die Ressource initiate wird von internen Verify-Komponenten während einer Laufzeit-MFA-Abfrage gestartet, wenn der verwendete Faktor das Integrationsmuster "initiate+validate" oder "initiate+wait" unterstützt.

Beispiel: smsotp oder push. Verify erwartet, dass die Antwort eine status enthält, die den Erfolg oder das Fehlschlagen der MFA-Initialisierung und eine Transaktions-ID angibt, die in den nachfolgenden "validate"- oder "wait for result"-Anforderungen enthalten ist. Das folgende Beispiel zeigt eine Beispielanfrage, die an Verify die initiate Ressource des Echtzeit-Webhooks gesendet wird. Je nach Webhook-Konfiguration können dieselben Nutzdaten direkt an den Ziel-MFA-Provider gesendet oder in eine API-Clientanforderung umgewandelt werden, die für den Zielprovider akzeptabel ist.
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>>"
    }
}
Hinweis: Der /initiate Pfad „ HTTP “ in diesem Beispiel hängt von der Webhook-Konfiguration ab.

Anforderungsdetails einleiten

Element Beschreibung
HTTP-Anforderung POST
HTTP-Header - Content-Type Der Inhaltstyp der Anforderungsnutzdaten ist immer application/json.
HTTP-Header - Accept Der von den Antwortnutzdaten erwartete Inhaltstyp ist immer application/json.
Nutzdaten Ein JSON-Objekt, das das zu validierende Token oder den zu validierenden Wert darstellt. Die Nutzdaten geben auch den Benutzer und die zugehörige MFA-Anmeldung oder -Registrierung an.
id

Obligatorisch. Die eindeutige Kennung der angemeldeten oder registrierten MFA-Faktorfunktion des Benutzers.
capability

Obligatorisch. Der Wert ist eine gültige Zeichenfolge. Sie muss einer der Funktionen entsprechen, die für den MFA-Provider konfiguriert sind, der dem Webhook zugeordnet ist.
attributes

Obligatorisch. Anforderungsspezifische zusätzliche Attribute.
attributes.username Obligatorisch. Der Name eines Benutzers im externen Providersystem, für das die MFA-Initialisierung angefordert wird.
Das folgende Codebeispiel zeigt ein Beispiel für die Nutzdaten der initiate-Antwort.
{
    "attributes": {
        "<<any name>>": "<<any value>>"
    },
    "status": "SUCCESS",
    "transactionId": "<<provider transaction identifier>>"
}

Antwortdetails einleiten

Elemente Beschreibung
Nutzdatentyp Ein JSON-Objekt, das den Status des MFA-Initialisierungsversuchs darstellt.
HTTP-Statuscode Siehe „ HTTP -Status “.
status Obligatorisch. Der Fertigstellungsstatus der Validierung. Gültige Werte sind SUCCESS, PENDING, TIMEOUT, CANCELED und FAILED.
Hinweis: Bei Rückgabe eines Status vonSUCCESSDer Aufruf von „Initiate“ führt bei dem Endbenutzer zu einer Fehlermeldung. „SUCCESS“ ist kein gültiger Status für den Initiate-Aufruf

Wenn der MFA-Anbieter OTP-Wiederholungsversuche unterstützt, muss der „Status“ als „PENDING“ zurückgegeben werden.
transactionId

Obligatorisch. Die Statuskennung der Authentifizierungsanforderung des Transaktions- oder anderen MFA-Providers. Wird vom Provider verwendet, um mit allen nachfolgenden Aufrufen "validate" oder "result poll" zu korrelieren.
attributes

Optional. Die zusätzlichen Attribute, die an den öffentlichen Verify-Client zurückgegeben werden, der die MFA-Abfrage ausgelöst hat. Alle Attribute und Werte können vorhanden sein.