Hinzufügen der Vonage Verify API zum Backend

Verwendung des Vonage Server SDK

Vonage stellt unter der Haube eine Standard-HTTP-API zur Verfügung. Das bedeutet, dass Sie theoretisch Verify integrieren könnten, indem Sie rohe HTTP-Anfragen selbst (zum Beispiel mit fetch, axios, usw.).

Warum also das Vonage Node SDK verwenden?

Die Verwendung des SDK ist hilfreich, weil:

• Die Authentifizierung ist einfacher und sicherer: Verify verwendet JWT-basierte Authentifizierung mit einem privaten Schlüssel. Das SDK wickelt den Signiervorgang korrekt ab, sodass Sie weniger Fehler machen können.

• Sauberer Code: Anstatt URLs, Kopfzeilen und Antwortformate manuell zu erstellen, rufen Sie Methoden wie newRequest() und checkCode().

• Bessere Wartung: Wenn Vonage die API aktualisiert oder neue Funktionen hinzufügt, wird in der Regel auch das SDK entsprechend aktualisiert.

• Weniger Probleme: Dinge wie die Formatierung von Anfragen und erwartete Felder werden einheitlich behandelt.

Fügen wir das SDK zu unserem app.js Datei:

Was ist hier los?

• Das Backend muss sich gegenüber Vonage beweisen: "Ich darf diese API anrufen."
• Vonage verwendet JWT (JSON Web Tokens), die mit Ihrem privaten Schlüssel signiert sind, für diesen Nachweis.
• Das SDK generiert und fügt das JWT automatisch an, wenn es Vonage aufruft.

Überprüfung starten: POST /verification

Dieser Endpunkt startet den Verifizierungsprozess. Die mobile App ruft Ihr Backend mit einer Rufnummer an. Ihr Backend fordert Vonage dann auf, eine Verifizierungsanfrage zu starten.

Was geschieht an diesem Endpunkt?

1. Der Nutzer gibt seine Telefonnummer in der mobilen App ein.
2. Die mobile App sendet die Telefonnummer an Ihr Backend.
3. Ihr Backend startet eine Verify-Anfrage:
   • erste Versuche Stille Authentifizierung
   • wenn das nicht abgeschlossen werden kann, fällt zurück auf SMS

Verstehen request_id und check_url:

• request_id: eine eindeutige Kennung für diesen Überprüfungsversuch. Betrachten Sie sie als eine Art "Quittungsnummer" für die Überprüfung.

• check_url: wird für die stille Authentifizierung verwendet. Ihr Backend gibt diese URL an die mobile App zurück. Die mobile App ruft sie auf, um zu beweisen, dass "diese Anfrage aus dem Mobilfunknetz der Telefonnummer stammt".

Überprüfen Sie den Verifizierungscode: POST /check-code

Wenn Silent Auth fehlschlägt oder nicht verfügbar ist, greift Vonage auf SMS zurück und der Benutzer erhält einen Code. Die mobile App sendet den Code an Ihr Backend zusammen mit dem request_id.

Rückrufe

Ein Rückruf (auch als Webhook) ist eine URL in Ihrem Backend, die ein externer Dienst (Vonage) aufrufen kann, um Sie über Ereignisse zu informieren.

Anstatt dass Ihr Backend ständig Vonage fragt: "Ist Silent Auth schon fertig? Was ist mit jetzt? Jetzt?"

Vonage kann Ihnen das Ergebnis zusenden: "Silent Auth beendet. Hier ist der endgültige Status."

Diese Push-Benachrichtigung ist der Rückruf.

Warum sind Rückrufe hier nützlich? Die stille Authentifizierung kann Zeit in Anspruch nehmen und asynchron abgeschlossen werden. Die Verwendung eines Rückrufs bedeutet:

• Ihr Backend muss Vonage nicht wiederholt abfragen
• Sie erhalten ein definitives Ereignis, wenn sich der Zustand der Überprüfung ändert
• Sie lässt sich in realen Systemen besser skalieren

Um die Callback-URL im Dashboard zu konfigurieren, öffnen Sie das Vonage Dashboard:

1. Gehe zu Applications
2. Wählen Sie Ihre Anwendung → Bearbeiten
3. Netzwerk-Register finden
4. Verify einschalten (SA)
5. Legen Sie die Callback-URL fest (wo Ihr Server lauscht), zum Beispiel:

https://your-domain.com/callback

Um den Rückruf zu implementieren, fügen Sie Ihrer Express-Anwendung eine neue Methode wie folgt hinzu:

Im Moment protokollieren wir das Ereignis, damit Sie sehen können, was Vonage sendet. Im nächsten Abschnitt werden wir es erweitern, um den Status zu speichern und die mobile App auf diese Aktualisierungen reagieren zu lassen.

Hinzufügen eines In-Memory-Status

Ein Prüfablauf ist nicht "eine Anfrage und fertig". Er hat einen Lebenszyklus:

• gestartet
• anhängig (stille Autorisierung / SMS)
• abgeschlossen oder nicht bestanden/abgelaufen

Wenn Sie nirgendwo einen Zustand speichern, hat Ihr Backend keine Erinnerung an das, was passiert ist, und:

• /callback kann nur Daten protokollieren (nicht sehr nützlich)
• Die App kann den aktuellen Status nicht zuverlässig erkennen
• Die Fehlersuche wird mühsam ("einmal hat es funktioniert, dann wieder nicht...")

Ein Geschäft bietet Ihnen eine einzige Quelle der Wahrheit.

In der Produktion würde man eine Datenbank verwenden (z.B. Postgres/Redis), aber für das Tutorial können wir einfach eine Map.

Schritt 1: Erstellen Sie den Shop mit einer Map

In Node.js kann eine Map ist eine einfache Möglichkeit, Schlüssel/Wertpaare im Speicher zu speichern.

Fügen Sie dies an den Anfang Ihrer app.js:

Fügen Sie eine Hilfsfunktion für die Validierung der erforderlichen Felder des Anfragebodys hinzu. Fügen Sie sie direkt unter der verificationStore Erklärung:

Dies gibt den Namen des ersten fehlenden Feldes zurück, oder null wenn alle Felder vorhanden sind.

Jeder Eintrag wird verschlüsselt durch request_id.

Ein typischer Eintrag könnte wie folgt aussehen:

Schritt 2: Speichern des Ausgangszustands bei der Erstellung einer Überprüfung

Wenn Sie anrufen verifyClient.newRequest(...) in /verificationerhalten Sie eine request_id.

Das ist der perfekte Schlüssel, um den Ausgangszustand zu speichern.

Im Inneren Ihres /verification Endpunkt, gleich nachdem Sie result:

Jetzt "merkt" sich das Backend, dass eine Überprüfung begonnen hat.

Schritt 3: Aktualisieren des Zustands, wenn der Callback Ereignisse empfängt

Ein Callback (Webhook) ist eine Mitteilung von Vonage an Ihr Backend: "Es hat sich etwas geändert. Hier ist der neue Status."

Anstatt nur die Nutzlast zu protokollieren, aktualisieren wir den gespeicherten Zustand:

Webhook-Zustellungen können wiederholt werden, was bedeutet, dass Sie dasselbe Ereignis mehrmals erhalten können. Die Aktualisierung des Speichers auf diese Weise ist natürlich idempotent: Das erneute Setzen des gleichen Status macht nichts kaputt.

Schritt 4: Hinzufügen eines Status-Endpunkts für die mobile Anwendung

Jetzt können wir einen einfachen Endpunkt bereitstellen, den die Anwendung aufrufen kann, um den aktuellen Zustand zu überprüfen:

Dies ist besonders nützlich für Silent Auth, da die App alle 1-2 Sekunden für einen kurzen Zeitraum abfragen kann, anstatt blind zu warten.

Schritt 5: Hinzufügen POST /next

Die /next Endpunkt weist Vonage an, den aktuellen Workflow-Kanal zu überspringen und zum nächsten zu wechseln. In unserem Fall bedeutet das, dass die stille Anmeldung übersprungen und sofort eine SMS gesendet wird.

Dies ist in der Android-App nützlich, wenn die Silent-Auth-Anfrage fehlschlägt (schlechtes Netzwerk, SDK-Fehler, etc.) - anstatt ~20 Sekunden zu warten, bis Vonage eine natürliche Zeitüberschreitung hat, ruft die App /next auf und der Benutzer erhält sofort eine SMS.