Umstellung von Numbers Verification API auf Verify Silent Auth

In diesem Leitfaden wird erläutert, wie Sie von einem stummen Authentifizierungsfluss unter Verwendung der Network Enablement API und der Numbers Verification API auf die einheitliche Verify API mit stummer Authentifizierung migrieren.

Die Verify-API unterstützt sowohl synchron und asynchrone Implementierungen der Stillen Authentifizierung. Dieser Leitfaden folgt der asynchrone die empfohlene Methode für die Integration der stillen Authentifizierung.

Vergleich zwischen alter und neuer Architektur

Bevor Sie mit der Migration beginnen, lesen Sie bitte die folgenden Abschnitte, um die Unterschiede zwischen der alten und der neuen Architektur zu verstehen.

Ältere Architektur: Netzaktivierung und Nummernüberprüfung

In der derzeitigen Konfiguration erfordert die stille Authentifizierung die Koordinierung von zwei separaten APIs. Zunächst wird die Network Enablement API aufgerufen, um zu prüfen, ob das Netz und der Gerätekontext des Benutzers die stille Authentifizierung unterstützen. Wenn dies der Fall ist, wird die Number Verification API verwendet, um die eigentliche stille mobile Identitätsprüfung durchzuführen.

Dieser Ansatz hat einige Einschränkungen:

• Es gibt keinen eingebauten Fallback, wenn die stille Überprüfung nicht unterstützt wird.
• Die Entwickler müssen beide APIs manuell orchestrieren.
• Die Fehler- und Wiederholungslogik muss auf der Client-Seite implementiert werden.

Neue Architektur: Verify mit stiller Authentifizierung

Die neue Architektur ersetzt den zweistufigen Ansatz durch eine einzige Integration unter Verwendung der Verify-API mit stiller Authentifizierung. Dieser einheitliche Ansatz reduziert die Komplexität, unterstützt Ausweichkanäle (wie SMS, Sprache, WhatsApp oder E-Mail), wenn eine stille Verifizierung nicht möglich ist, und verarbeitet Webhook-Rückrufe automatisch.

Wichtigste Unterschiede

In der nachstehenden Tabelle sind die wichtigsten Unterschiede zwischen dem alten und dem neuen Konzept aufgeführt:

Schritte der Migration

Führen Sie die folgenden Schritte aus, um von Network Enablement und Numbers Verification API zu Verify API mit Silent Authentication zu migrieren:

Schritt 1: Aktualisieren Sie Ihre Applications-Einstellungen

Schritt 2: Ersetzen Sie den Legacy Flow durch Verify API

Schritt 3: Authentifizierungsmethode aktualisieren

Schritt 4: Aktualisieren der Anforderungsstruktur

Schritt 5: Übergabe der check_url an die Mobile App

Schritt 6: Verarbeiten des action_pending Callback

Schritt 7: Mobile App folgt den Weiterleitungen und erhält den Code

Schritt 8: Bestätigen Sie den Verifizierungscode

Schritt 9: Verarbeiten des Zusammenfassungsrückrufs

Aktualisieren Sie Ihre Applications-Einstellungen

In der Vonage Application Dashboardöffnen Sie die Einstellungen Ihrer Anwendung. Unter Funktionen > Netzwerk-RegisterAktualisieren Sie den Verify-Ereignisstatus-Callback mit der URL, die Ihr Backend erhält Webhook Ereignisse (z.B., action_pending, completed).

Ersetzen Sie den Legacy Flow durch Verify API

Sobald die mobile Anwendung die Authentifizierung auslöst, muss Ihr Backend den Authentifizierungsfluss starten:

Alter Fluss:

1. Netzwerkaktivierungs-API aufrufen.
2. Wenn das Netz unterstützt wird, rufen Sie die Number Verification API auf, um die Netzabdeckung zu prüfen.

Neue Strömung:

1. Rufen Sie die Verify-API mit der silent_auth Arbeitsablauf.
2. Wenn die stille Überprüfung fehlschlägt, wird automatisch ein Ausweichkanal (z. B. SMS, Sprache, WhatsApp oder E-Mail) ausgelöst, sofern dies im Workflow definiert wurde (siehe Aktualisieren Sie die Anforderungsstruktur).

Authentifizierungsmethode aktualisieren

Die Verify-API unterstützt zwei Authentifizierungsmethoden: Grundlegende Authentifizierung und JWT (Bearer Token). Siehe dazu die Verify-Authentifizierungsleitfaden für Einzelheiten darüber, wann die einzelnen Methoden zu verwenden sind und wie die Berechtigungsnachweise zu erstellen sind.

Aktualisieren Sie die Anforderungsstruktur

Verify API verwendet eine Arbeitsablauf Array, um die Reihenfolge der Verifizierungskanäle zu definieren. Die stille Authentifizierung muss der erste Schritt im Arbeitsablauf sein, wie im folgenden Beispiel gezeigt:

{
  "brand": "ACME",
  "workflow": [
    {
      "channel": "silent_auth",
      "to": "447700900000",
    },
    {
      "channel": "sms",
      "to": "447700900000"
    }
  ]
}   

Pass die check_url zur Mobile App

Nach dem Aufruf der Verify-API erhalten Sie eine synchrone Antwort ähnlich wie in diesem Beispiel:

{
  "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
  "check_url": "https://api.nexmo.com/v2/verify/c11236f4.../silent-auth/redirect"
}   

Die Antwort enthält die check_url Parameter, der ähnlich wie der auth_url die bei der Numbers-Prüfung verwendet wird. Die mobile Anwendung muss eine HTTP-

Sie können auch die gleichen check_url später in einem Ereignis-Callback (siehe Übergeben Sie die check_url an die Mobile App), so dass Sie sie je nach Ihrer Implementierung aus einer der beiden Quellen an die Anwendung übergeben können.

Behandeln Sie die action_pending Rückruf

Kurz nach der Anfrage sendet Vonage einen Ereignis-Callback an Ihre Webhook-URL, die in Aktualisieren Ihrer Applications-Einstellungen.

{
  "request_id": "...",
  "type": "event",
  "channel": "silent_auth",
  "status": "action_pending",
  "action": {
    "type": "check",
    "check_url": "https://eu.api.silent.auth/..."
  }
}   

Sie können die check_url entweder aus der ursprünglichen API-Antwort (Aktualisieren Sie die Anforderungsstruktur) oder diesen Callback, um die stille Anmeldung in der App zu starten.

Mobile App folgt Umleitungen und empfängt Code

Die mobile App führt eine GET Anfrage an den check_url. Sie folgt einem oder mehreren HTTP 302 Weiterleitungen und erhalten schließlich eine Antwort:

{
  "request_id": "...",
  "code": "si9sfG"
}   

Bei Erfolg muss dieser Code im nächsten Schritt validiert werden.

Bestätigen Sie den Verifizierungscode

Senden Sie eine POST Anfrage von der mobilen Anwendung an die Verify-API, um den Code zu validieren:

POST https://api.nexmo.com/v2/verify/{request_id}
Authorization: Bearer {access_token}
Content-Type: application/json  

Mit der folgenden Stelle:

{
  "code": "si9sfG"
}   

Wenn alles gut geht, wird die Antwort vom Backend ähnlich wie in diesem Beispiel aussehen:

{
  "request_id": "...",
  "status": "completed"
}   

Behandlung des Zusammenfassungsrückrufs

Sobald die Überprüfung abgeschlossen ist, sendet Vonage einen letzten Rückruf an Ihren Webhook:

{
  "request_id": "...",
  "type": "event",
  "channel": "silent_auth",
  "status": "completed"
}   

Damit wird bestätigt, dass der Prüfvorgang abgeschlossen ist.

Nächste Schritte

• Testen Sie Ihre Integration in einer Sandkastenumgebung. Verwenden Sie Test Numbers und das Developer Dashboard, um sowohl Silent- als auch Fallback-Szenarien zu validieren.
• Prüfen Sie unser Leitfaden für bewährte Praktiken der stillen Authentifizierung.
• Überwachen Sie Webhook-Ereignisse. Stellen Sie sicher, dass Ihr Backend Status-Callbacks korrekt verarbeitet (z. B., action_pending, completed, failed).

Weitere Einzelheiten finden Sie in der API-Dokumentation verifizieren.