Authentifizierung

Verify API unterstützt zwei Arten der Authentifizierung:

• Grundlegende Authentifizierung
• JWT

Wann sollten Sie die Basisauthentifizierung oder JWT verwenden?

Verify V2 unterstützt zwei Authentifizierungsmethoden: Basis-Authentifizierung und JWT Bearer-Authentifizierung. Es ist wichtig, die Unterschiede zwischen diesen beiden Methoden zu verstehen, um eine reibungslose Migration zu gewährleisten und die Vorteile der V2-Funktionen voll auszuschöpfen.

Sie können beide Möglichkeiten nutzen, aber nicht beide gleichzeitig. Im Allgemeinen, wir empfehlen die Verwendung von JWT Authentifizierung bei der Arbeit mit der Verify-API. Die Basisauthentifizierung ist zwar für den Einstieg einfacher, unterstützt aber nicht die Stille Authentifizierung Kanal.

Grundlegende Authentifizierung

Bei der einfachen Authentifizierung werden Ihr API-Schlüssel und Ihr API-Geheimnis gesendet. Base64-verschlüsselt im Authorization Kopfzeile. Sie finden diese Anmeldeinformationen in Ihrem API-Einstellungen im Vonage Dashboard.

Dies ist der einfachste Weg, um mit Verify V2 zu beginnen, da keine Einrichtung der Vonage Applications erforderlich ist und Ihre Anmeldedaten sofort in der Vonage Dashboard.

Wie es funktioniert

Authorization: Basic <base64(api_key:api_secret)>

Erstellen des Anfragekopfes

• Verknüpfen Sie zunächst Ihren API-Schlüssel und Ihr Geheimnis: API_KEY:API_SECRET.
• Dann, Base64 kodieren das Ergebnis. Mehr erfahren hier.
• Schließlich senden Sie es in der Anfrage als Authorization: Basic BASE64_ENCODED_STRING.

Sie können dies innerhalb Ihres Anwendungscodes tun - zum Beispiel in JavaScript:

Beispiel-Anfrage

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

Sie können die Base64-kodierte Zeichenfolge aus api_key:api_secret mit einem beliebigen Standard-Base64-Kodierungstool oder einer Bibliothek.

Beschränkungen

Die Basisauthentifizierung ermöglicht den Zugriff auf den zentralen Verify V2-Anforderungsablauf (Senden, Prüfen, Abbrechen, Auslösen des nächsten Workflows), aber es gibt zwei wichtige Einschränkungen:

• Callbacks/Webhooks werden nicht unterstützt. Der Empfang von Ereignis- oder Zusammenfassungsrückrufen erfordert eine JWT-Bearer-Authentifizierung zusammen mit einer von Vonage-Applikation, die mit einer Status-URL konfiguriert ist.
• ACL-Unterstützung (Access Control List) ist nicht verfügbar. Mit JWT-Tokens können Sie Berechtigungen für bestimmte API-Endpunkte festlegen, was mit Basic Auth nicht möglich ist.

Angesichts dieser Einschränkungen ist Basic Auth am besten für erste Tests und POC-Integrationen geeignet. Für Produktionseinsätze wird die JWT-Bearer-Authentifizierung dringend empfohlen.

JWT

A JWT (JSON Web Token) ist ein offener Standard (RFC 7519) für die sichere Übermittlung von Informationen zwischen Parteien in Form eines JSON-Objekts. Das Objekt kann optional verschlüsselt und mit einem privaten/öffentlichen Schlüssel signiert werden.

Die JWT-Bearer-Authentifizierung verwendet ein JSON-Web-Token, das mit dem privaten Schlüssel Ihrer Vonage Application signiert ist. Diese Methode schaltet den vollen Funktionsumfang von Verify V2 frei, einschließlich Event- und Summary-Callbacks, Webhook-Konfiguration und ACL-scoped Tokens.

Wie es funktioniert

Authorization: Bearer <JWT>

Das JWT wird mit Ihrer Anwendungs-ID und Ihrem privaten Schlüssel generiert, die Sie beide bei der Erstellung einer Vonage Application im Dashboard erhalten haben.

Um ein JWT zu erzeugen, benötigen Sie Ihre application ID und private key, die beide in der Applikation Einstellungen in Ihrem Dashboard.

Es gibt mehrere Möglichkeiten, ein neues JWT zu erzeugen:

• Die Verwendung des JWT-Online-Generator.

• Die Verwendung des Vonage CLI-Werkzeug. Der private Schlüssel und eine Anwendungs-ID müssen angegeben werden:

Bitte beachten:

• Wenn Sie eines der Vonage-Programme verwenden Server-SDKs müssen Sie kein separates JWT erzeugen, da alle SDKs die Erzeugung von JWT-Tokens unterstützen.

• Wenn Sie das JWT nicht mit einem externen Tool oder einer Bibliothek, wie z. B. den Vonage SDKs, generieren möchten, können Sie Ihre eigene JWT-Generierung implementieren. Die wie man ein JWT erzeugt Blogpost enthält Beispiele in JavaScript und Python, die zeigen, wie man ein JWT ohne externe Abhängigkeiten generiert.

Nach der Generierung sollten die Benutzer in der Lage sein, das Token für den Zugriff auf geschützte Endpunkte zu verwenden. Dies geschieht in der Regel über den Authorization-Header unter Verwendung des Bearer-Schemas:

Setup-Schritte für Verify V2

1. Erstellen Sie eine Vonage-Applikation in der Vonage Dashboard.
2. Generieren Sie ein öffentliches/privates Schlüsselpaar - laden Sie den privaten Schlüssel herunter und bewahren Sie ihn sicher auf.
3. Aktivieren Sie Verify V2 für die Anwendung und konfigurieren Sie die Status-URL (Webhook-Endpunkt) für den Empfang von Rückrufen.
4. Erzeugen Sie ein JWT, das mit Ihrer Application ID und Ihrem privaten Schlüssel signiert ist. Sie können die JWT-Generatordie Vonage CLIoder ein Vonage SDK.
5. Fügen Sie das JWT in alle API-Anfragen ein, indem Sie die Authorization: Bearer Kopfzeile.

Beispiel-Anfrage

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

JWT-Tokens haben eine maximale Verweildauer (TTL) von 24 Stunden. Stellen Sie sicher, dass Ihre Integration die Token vor dem Ablauf aktualisiert, um zu vermeiden 401 Unauthorized Fehler.

Was JWT freischaltet

• Zusammenfassende Rückrufe - am Ende eines jeden Überprüfungsauftrags einen vollständigen Statusbericht erhalten.
• Ereignis-Rückrufe - Echtzeit-Ereignisse während der Anfrage empfangen (z. B. für die Kanäle Silent Auth und WhatsApp Interactive).
• ACL-gesperrte Token - Token-Berechtigungen auf bestimmte Endpunkte beschränken, um die Sicherheit zu erhöhen.
• Webhook-Konfiguration - konfigurieren verify_event_url und verify_status_url pro Vonage Applikation.

Migration der Authentifizierung von Verify Legacy (V1)

Eine der wichtigsten Änderungen bei der Migration von Verify V1 zu Verify V2 ist die Handhabung der Authentifizierung.

In Verify V1 erfolgte die Authentifizierung durch die Übergabe von api_key und api_secret als Abfrageparameter oder im Anfragekörper. Diese Methode wird in Verify V2 nicht unterstützt.