Authentifizierung

Verify API unterstützt zwei Arten der Authentifizierung:

• Grundlegende Authentifizierung
• JWT

Wann sollten Sie die Basisauthentifizierung oder JWT verwenden?

Verify unterstützt zwei Authentifizierungsmethoden: die Basic-Authentifizierung und die JWT-Bearer-Authentifizierung. Es ist wichtig, die Unterschiede zwischen diesen beiden Methoden zu verstehen, um eine reibungslose Migration zu gewährleisten und die Funktionen von Verify 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 zu beginnen, da keine Einrichtung der Vonage-Application erforderlich ist und Ihre Anmeldedaten sofort über die 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:

const credentials = btoa('YOUR_API_KEY:YOUR_API_SECRET');

const response = await fetch('https://api-eu.vonage.com/v2/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + credentials
  },
  body: JSON.stringify({ ... })
});

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

Basic Auth ermöglicht den Zugriff auf den zentralen Verify-Anforderungsablauf (Senden, Prüfen, Abbrechen, nächsten Workflow auslösen), es gibt jedoch 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 erschließt den vollen Funktionsumfang von Verify, einschließlich Ereignis- und Zusammenfassungs-Callbacks, Webhook-Konfiguration und ACL-gebundenen 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:

Authorization: Bearer <JWT>

Einrichtungsschritte für „Verify“

1. Erstellen Sie eine Vonage-Applikation in der Vonage Dashboard. Gehen Sie im linken Bereich zu Erstellen > Applications.
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 für die Anwendung und konfigurieren Sie die Status-URL (Webhook-Endpunkt), um Rückrufe zu empfangen.
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 aus Verify Legacy

Eine der wichtigsten Änderungen bei der Migration von Verify Legacy zu Verify betrifft die Art und Weise, wie die Authentifizierung gehandhabt wird.

In „Verify Legacy“ erfolgte die Authentifizierung durch die Übergabe von api_key und api_secret als Abfrageparameter oder im Request-Body. Diese Methode wird in Verify nicht unterstützt.