Authentifizierung

Die Vonage APIs unterstützen verschiedene Authentifizierungsmethoden, je nachdem, welches Produkt Sie verwenden:

1 Messages unterstützt sowohl die JWT- als auch die Basis-Authentifizierung. Die Basis-Authentifizierung unterstützt jedoch keine Webhooks oder erweiterte Funktionen wie ACLs. Für die meisten Anwendungsfälle empfehlen wir die JWT-Authentifizierung. Siehe Messages API-Authentifizierung

2 Verify unterstützt sowohl die JWT- als auch die Basisauthentifizierung. Die Basisauthentifizierung unterstützt jedoch keine Webhooks oder erweiterte Funktionen wie ACLs.

3 SIP Trunking verwendet Digest-Authentifizierung Methode mit dem API-Schlüssel als Benutzer und dem API-Geheimnis als Passwort.

Inhalt

In diesem Dokument erfahren Sie mehr über die Authentifizierung mit den folgenden Mitteln:

API-Schlüssel und Geheimnis

Wenn Sie einen Vonage Account erstellen, werden ein API-Schlüssel und ein Geheimnis für Sie erstellt. Diese befinden sich in Ihrem Account-Einstellungen im Vonage Dashboard. Sie sollten diese immer sicher aufbewahren und diese Details niemals weitergeben: Seien Sie vorsichtig, wenn Sie sie zu Ihrer Codebasis hinzufügen, um sicherzustellen, dass sie nicht mit jemandem geteilt werden, der sie böswillig verwenden könnte. Wenn Sie Nachrichtensignaturenwerden diese mit Hilfe des SIGNATURE_SECRET und nicht die API_SECRET; beide Werte finden sich in Ihrem Account-Einstellungen.

Hinweis: Das Geheimnis sollte immer sicher aufbewahrt und niemals weitergegeben werden. Seien Sie vorsichtig, wenn Sie es zu Ihrer Codebasis hinzufügen, um sicherzustellen, dass es nicht an jemanden weitergegeben wird, der es böswillig verwenden könnte. Lesen Sie mehr über das Beste Sicherheitspraktiken für Ihren Vonage Account.

Die APIs von Vonage können Ihren API-Schlüssel und Ihr Geheimnis auf verschiedene Weise erfordern.

Grundlegende Authentifizierung

Einige neuere Vonage-APIs erfordern eine Authentifizierung mit einem API-Schlüssel und einem Geheimnis, die Base64-kodiert in der Datei Authorization Kopfzeile.

Für diese APIs senden Sie Ihren API-Schlüssel und Ihr Geheimnis auf folgende Weise:

Authorization: Basic base64(API_KEY:API_SECRET)

Wenn Ihr API-Schlüssel aaa012 und Ihr API-Geheimnis waren abc123456789würden Sie den Schlüssel und das Geheimnis mit einer : (Doppelpunkt) und kodieren sie dann mit Base64-Codierung, um einen Wert wie diesen zu erzeugen:

Authorization: Basic YWFhMDEyOmFiYzEyMzQ1Njc4OQ==

Eine Website zur Erzeugung von Base64-kodierten Zeichenketten finden Sie hier:

Einzelheiten zur Kodierung von Base64-Zeichenfolgen in einer Vielzahl von Programmiersprachen finden Sie auf den folgenden Websites:

Geheime Rotation

Es ist möglich, zwei API-Geheimnisse gleichzeitig für einen API-Schlüssel zu verwenden. Auf diese Weise können Sie ein zweites API-Geheimnis erstellen und es testen, bevor Sie das bestehende API-Geheimnis in Ihrem Produktionsnetzwerk widerrufen. Das Verfahren zur Rotation des API-Geheimnisses besteht aus den folgenden Schritten:

  1. Erstellen Sie ein zweites API-Geheimnis in Ihrer Account-Einstellungen oder durch die Verwendung der geheime Rotation API.
  2. Aktualisieren Sie einen oder mehrere Ihrer Server, um das neu erstellte API-Geheimnis für Aufrufe der Vonage-APIs zu verwenden.
  3. Testen Sie, ob es keine Verbindungsprobleme gibt, und verteilen Sie das API-Geheimnis-Update auf die übrigen Server.
  4. Löschen Sie das ersetzte API-Geheimnis

JSON-Web-Token

JSON-Web-Token (JWTs) sind ein kompaktes, URL-sicheres Mittel zur Darstellung von Forderungen, die zwischen zwei Parteien übertragen werden sollen. Eine vollständige Liste der APIs, die JWTs verwenden, finden Sie in der Tabelle über.

Header und Nutzlast

JWTs bestehen aus einem Header und einem Payload. Die Werte für den Header sind:

Name Beschreibung Erforderlich
alg Der Verschlüsselungsalgorithmus, der zur Erzeugung des JWT verwendet wird. RS256 wird unterstützt.
typ Die Token-Struktur. Eingestellt auf JWT.

Die Werte für die Nutzlastforderung sind:

Name Beschreibung Erforderlich
application_id Die eindeutige ID, die Ihrer Anwendung von Vonage zugewiesen wurde.
iat Der UNIX-Zeitstempel in UTC + 0, der den Zeitpunkt angibt, zu dem das JWT angefordert wurde.
jti Ein eindeutiger String-Bezeichner des JWT.
nbf Der UNIX-Zeitstempel in UTC + 0, der den Zeitpunkt angibt, zu dem das JWT gültig wurde.
exp Der UNIX-Zeitstempel bei UTC + 0, der den Zeitpunkt angibt, an dem das JWT nicht mehr gültig ist. Ein Mindestwert von 30 Sekunden ab dem Zeitpunkt, zu dem das JWT erzeugt wurde. Ein Höchstwert von 24 Stunden ab dem Zeitpunkt der Erstellung des JWT. Ein Standardwert von 15 Minuten ab dem Zeitpunkt der Erstellung des JWT.

JWTs generieren

Verwendung der Vonage CLI zur Erzeugung von JWTs

Die Vonage CLI bietet einen Befehl zur Erzeugung eines JWT.

Ein Beispiel für die Erstellung eines JWT für eine Anwendung lautet wie folgt:

# A command with parameters
vonage jwt create `
--app-id='00000000-0000-0000-0000-000000000000' `
--private-key=./private.key

# Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzYyODE5NDYsImp0aSI6IjBmZjcwZDNmLTAzN2EtNGY4MC04ODZjLWI3MmM3MmQyMWNmMiIsImlhdCI6MTczNjI4MTA0NiwiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.gA7jClpqaZ2OoS0iri-zGCbda4jO7C0M8mka0EnSyjlds1EeY8fNoBEx3FTXHfkkzzrj0TskrWc_dcs1wuM8Kx55c5rLQ7taVpDAYopKSc_CeeOaad8S6aWnRkTUTNeduO4aIn-0CbyRTluBYsH1RBqYBQvobuQIDEwbFw8xBgx0UfREMMN6DAWknR57eiVXN9x_oD6CGQJ1yV3025nGboeMsP9YgX4Nwc-rE2r8c1ZGwCLO81x8i19Qil3Nwu5q1nzouyavQjIw00B_TZkushnI1ufdi_GNqk-h5q2HvGkg7Pj9bVkZHFdVTO8im03JYNyJmcV83vnpjOLuCFRzxQ

Der betreffende private Schlüssel wird aus dem Anwendungs-Dashboard oder aus vonage apps create. Sie können diese Informationen für die CLI speichern, indem Sie vonage auth set. Der Inhalt des privaten Schlüssels wird dann entweder in der .vonagerc Datei oder $HOME/.vonage/config.json.

Weitere Informationen über die Vonage CLI finden Sie in deren Repository auf GitHub.

Beispiele für die Verwendung der Vonage-Bibliotheken zur Erzeugung von JWTs finden Sie hier unter. Wenn Sie keine Vonage-Bibliothek verwenden, sollten Sie sich an RFC 7519 JWTs zu implementieren.

Vonage Client-SDKs

Die Vonage Kunde und Video SDKs verwenden JWTs zur Authentifizierung, wenn sich ein Client mit Vonage verbindet. Diese JWTs werden unter Verwendung der Anwendungs-ID und des privaten Schlüssels generiert, die bereitgestellt werden wenn eine neue Anwendung erstellt wird.

Ansprüche

Mit diesem private.key und der Anwendungs-ID können Sie ein neues JWT erstellen. Um einen Benutzer bei einem Vonage-Client anzumelden, muss das JWT die folgenden Angaben enthalten:

Vonage Client SDK
Anspruch Beschreibung
sub Der "Betreff". Der Betreff ist in diesem Fall der Name des Benutzers, der mit Ihrer Vonage-Applikation verbunden ist.
acl Zugriffskontrollliste. Das Client SDK verwendet diese als Berechtigungssystem für Benutzer. Lesen Sie mehr darüber in der ACL-Übersicht.
application_id Dies ist die ID der von Ihnen erstellten Vonage Application.
iat "Issued at time" Dies ist der Zeitpunkt, zu dem das JWT ausgestellt wurde, in Unix-Epochenzeit.
jti "JWT-ID". Dies ist ein eindeutiger String-Bezeichner für dieses JWT.
exp "Expiration time" Dies ist der Zeitpunkt in der Zukunft, an dem das JWT abläuft, in Unix-Epochenzeit.

Die exp Anspruch ist fakultativ. Wenn der Anspruch nicht angegeben wird, läuft das JWT standardmäßig nach 15 Minuten ab. Die maximale Verfallszeit für ein JWT beträgt 24 Stunden. JWTs sollten in der Regel kurzlebig sein, da es trivial ist, ein neues JWT zu erstellen und einige JWTs mehrere weitreichende Berechtigungen haben können.

Beispiel Client SDK JWT-Nutzdaten

Wenn alle Angaben gemacht worden sind, sollten die resultierenden Angaben wie folgt aussehen:

{
  "iat": 1532093588,
  "jti": "705b6f50-8c21-11e8-9bcb-595326422d60",
  "sub": "alice",
  "exp": "1532179987",
  "acl": {
    "paths": {
      ...
    }
  },
  "application_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

( ... Schnipsel ist abgeschnitten)

Vonage Video Client SDK
Anspruch Beschreibung
sub Der "Betreff". Der Betreff sollte in diesem Fall die Zeichenfolge video.
acl Zugriffskontrollliste. Das Client SDK verwendet diese als Berechtigungssystem für Benutzer. Lesen Sie mehr darüber in der ACL-Übersicht.
application_id Dies ist die ID der von Ihnen erstellten Vonage Application.
session_id Dies ist die ID des Sitzung die Sie erstellt haben.
scope Dies ist der Geltungsbereich des Tokens. Es sollte die Zeichenfolge session.connect.
role Dies ist die Rolle des Tokens. Es kann ein Bereich von String sein Werte je nachdem, welche Berechtigungen Sie diesem Token erteilen wollen.
data Diese benutzerdefinierten Metadaten können Sie optional hinzufügen, um das Token zu beschreiben. Dies ist eine Zeichenkette, die auf 1000 Zeichen.
initial_layout_class_list Auf diese Weise können Sie beim Senden optional die anfängliche Layout-Klassenliste für vom Client veröffentlichte Streams.
iat "Issued at time" Dies ist der Zeitpunkt, zu dem das JWT ausgestellt wurde, in Unix-Epochenzeit.
jti "JWT-ID". Dies ist ein eindeutiger String-Bezeichner für dieses JWT.
exp "Expiration time" Dies ist der Zeitpunkt in der Zukunft, an dem das JWT abläuft, in Unix-Epochenzeit.

Die exp Anspruch ist fakultativ. Wenn der Anspruch nicht angegeben wird, läuft das JWT standardmäßig nach 24 Stunden ab. Die maximale Verfallszeit für ein Video SDK JWT beträgt 30 Tage. JWTs sollten in der Regel kurzlebig sein, da es trivial ist, ein neues JWT zu erstellen und einige JWTs mehrere weitreichende Berechtigungen haben können. Stellen Sie immer sicher, dass Sie versuchen, ein exp Zeit auf die kürzeste Zeitspanne, die für Ihre Anwendung machbar ist.

Beispiel Video Client SDK JWT-Nutzdaten
{
  "scope": "session.connect",
  "session_id": "1_MX44YjY4NTFmZS01NjdjLTRlODYtYWRmOC0zYmVhODM2MzNjNjB-fjE3NDIzMDY0ODY0NjZ-WS9FOHhybUdHV0JtTGZYTEV2aVlwV1N4fn5-",
  "role": "moderator",
  "initial_layout_class_list": "",
  "sub": "video",
  "acl": {
    "paths": {
      "/session/**": {}
    }
  },
  "jti": "c04c96ba-3229-4fd4-9f55-406b6a6eb485",
  "iat": 1742306486,
  "exp": 1742307386,
  "application_id": "8b6851fe-567c-4e86-adf8-3bea83633c60"
}

Zugriffskontrollliste (ACL)

In der Beispiel für die Nutzlast einer JWT-Anfrage oben, beachten Sie, wie die acl Anspruch hat eine paths Objekt. Das Pfadobjekt enthält eine Liste von Endpunkten, die bestimmten Berechtigungen entsprechen, die ein Benutzer bei der Verwendung des Client SDK hat.

Nachfolgend finden Sie die Liste der Endpunkte, auf die Sie einem Benutzer Zugriff gewähren können:

Endpunkt Beschreibung Erforderlich für
/*/rtc/** Erstellen einer Signalisierungssitzung zum Empfangen von Ereignissen und Senden von Metriken In-App-Anrufe/Nachrichten
/*/sessions/** Anmelden als In-App Voice- oder Chat-Benutzer In-App-Anrufe/Nachrichten
/*/users/** Abrufen von Benutzergesprächen, Benutzersitzungen und Benutzerobjekten In-App-Anrufe/Nachrichten
/*/conversations/** Erstellen und Verwalten von Konversationen und Senden/Empfangen von Nachrichten In-App-Anrufe/Nachrichten
/*/knocking/** Telefonanrufe starten In-App-Anrufe
/*/devices/** Gerät für den Empfang von Push-Benachrichtigungen registrieren In-App-Anrufe/Nachrichten
/*/legs/** Erstellen und Verwalten von Abschnitten in einem Gespräch In-App-Anrufe
/*/session/** Verbinden mit einer Videositzung Video

Sie sollten dem Benutzer, den Sie erstellen, die Berechtigung geben, nur auf die relevanten Pfade zuzugreifen. Wenn der Voice Client SDK-Benutzer zum Beispiel keine Informationen über sein Benutzerobjekt oder andere Benutzer abrufen muss, sollten Sie die Option users Pfad. Zur weiteren Veranschaulichung: Wenn Sie die /*/conversations/** Pfad zur ACL eines JWT, kann der Benutzer Unterhaltungen erstellen und verwalten. Auch wenn dies der nur ACL gesetzt ist, hat der Benutzer nur Zugriff auf die /conversations Endpunkt.

Hinweis: Die Verwendung von Platzhaltern in Ihren ACL-Pfaden (z. B. /*/conversations/**) erlaubt dem JWT-Token den Zugriff auf alle Operationen für diesen Endpunkt. Es wird dringend empfohlen, Ihre ACL-Pfade wie unten dargestellt genauer zu steuern.

Granulare ACL-Pfade

Oben haben wir uns angesehen, wie man Benutzern Zugriff auf Endpunkte gewährt. Sie können den Zugriff auch auf der Grundlage von Unterpfaden und HTTP-Methoden einschränken oder gewähren. Auf diese Weise können Sie sehr detailliert festlegen, welche Berechtigungen ein Token haben soll. In Ihrer Voice Client SDK-Anwendung möchten Sie zum Beispiel, dass Benutzer Informationen über ein Gespräch abrufen können:

{
  "acl": {
    "paths": {
      "/*/conversations/**": {}
    }
  }
}

Die obigen ACL-Pfade ermöglichen jeder mit diesem Token, um Anfragen zu stellen an jede Conversation API-Endpunkt, der mit Ihrer Vonage-Anwendung verknüpft ist. Dadurch kann derjenige, der dieses Token besitzt, eine Liste der laufenden Konversationen in Ihrer Anwendung abrufen, neue Konversationen erstellen oder mehr. Um dies abzuschwächen, können Sie angeben, welche Pfade speziell zugänglich sein sollen und welche HTTP-Methoden auf diesen Pfaden verwendet werden dürfen.

{
  "acl": {
    "paths": {
      "/*/conversations/*": {
        "methods": [
          "GET"
        ]
      }
    }
  }
}

Dieser neue ACL-Pfad ermöglicht es jedem, der dieses Token besitzt nur ein GET Anfrage an eine bestimmte Konversation und keine weiteren Unterpfade oder Operationen. Dies ist weitaus restriktiver als zuvor.

Minimale ACL-Pfade für Client-SDKs

Nachfolgend finden Sie die minimalen ACL-Pfade, die zur Durchführung verschiedener Aktionen in den Vonage Client SDKs erforderlich sind. Um die Unterstützung für weitere Endpunkte basierend auf Ihrem Anwendungsfall hinzuzufügen, lesen Sie die ACL-Tabelle und fügen sie so restriktiv wie möglich hinzu.

Dies unterstützt den grundlegenden Anwendungsfall der Erstellung einer Sitzung unter Verwendung von serverCall, reconnectCallund die Möglichkeit, einen Anruf anzunehmen, abzuweisen oder aufzulegen.

{
  "acl": {
    "paths": {
      "/*/sessions/**": { "methods": ["POST"] },
      "/*/conversations/*": { "methods": ["GET"] },
      "/*/conversations/*/rtc/*/answer": { "methods": ["POST"] },
      "/*/conversations/*/rtc/*/offer/*": { "methods": ["POST"]},
      "/*/conversations/*/members/*": { "methods": ["PUT", "DELETE"] },
      "/*/knocking/**": { "methods": ["POST", "DELETE"] },
      "/*/legs/**": { "methods": ["POST", "GET"] },
      "/*/v2/rtc/**": { "methods": ["POST", "GET"] }
    }
  }
}

Generierung von JWTs mit der Vonage CLI

Die Server-SDKs enthalten Methoden zur Erzeugung von JWT-Tokens. Sie können jedoch die Vonage CLI um dies ebenfalls zu tun. Dies ist besonders bei Tests hilfreich.

# A command with parameters
vonage jwt create `
--app-id='00000000-0000-0000-0000-000000000000' `
--private-key=./private.key `
--sub='Alice' `
--acl='{\"paths\":{\"\/*\/users\/**\":{},\"\/*\/conversations\/**\":{},\"\/*\/sessions\/**\":{},\"\/*\/devices\/**\":{},\"\/*\/push\/**\":{},\"\/*\/knocking\/**\":{},\"\/*\/legs\/**\":{}}}'

# Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2wiOnsicGF0aHMiOnsiLyovcnRjLyoqIjp7fSwiLyovdXNlcnMvKioiOnt9LCIvKi9jb252ZXJzYXRpb25zLyoqIjp7fSwiLyovc2Vzc2lvbnMvKioiOnt9LCIvKi9kZXZpY2VzLyoqIjp7fSwiLyovcHVzaC8qKiI6e30sIi8qL2tub2NraW5nLyoqIjp7fSwiLyovbGVncy8qKiI6e319fSwiZXhwIjoxNzQxMTgyMzA3LCJzdWIiOiJBbGljZSIsImp0aSI6Ijg1MTViNzk2LTA1YjktNGFkMS04MTRkLTE1NWZjZTQzZWM1YiIsImlhdCI6MTc0MTE4MTQwNywiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.BscMdDXZ1-nuLtKyPJvw9tE8E8ZjJvTPJPMT9y0TjPz4Q7qqNaqxcjglc5QPtYEjh2YpZH6btSKbUF4XTClI026Hl5_QOBlnayYo7jXwhba16fa5PeyzSf30QFGFrHbANwrQJFVCjd329SZUpwK4GxgB1gf230NhbfmkhegKezqicru2WTGCKm8kQncYliFwIEYUlcRAb2c8xcaVrn_6QNNahyeJRwGFfWpIkX0Oe-S4RDlPjoq47_gYWac9MmaetB4Dd3Yp531AuniGV5JiIShkaEwuY4Zyov4Hcmajm4Lm_UFY119la7vzHis0P7cT9pPUDe5cyPj7eT8-VhitfQ

Verwendung der Server-SDKs

Es wird erwartet, dass der zugehörige Server für Ihre Vonage Anwendung JWTs für die Client SDKs generiert. Hier sind einige Beispiele für die Verwendung der Vonage Server SDKs:

Version 3 des Vonage Node Server SDK enthält ein Paket zur Erzeugung von JWT-Tokens. Es kann auch ein JWT generieren unter Verwendung der entsprechenden Angaben.

const { tokenGenerate } = require('@vonage/jwt');

const privateKey = readFileSync('path/to/private.key');

const aclPaths = {
  "paths": {
    ...
  }
}

const token = tokenGenerate("aaaaaaaa-bbbb-cccc-dddd-0123456789ab", privateKey, {
      //expire in 24 hours
      exp: Math.round(new Date().getTime()/1000)+86400,
      sub: "Alice",
      acl: aclPaths,
    });

( ... Schnipsel ist abgeschnitten)

Wenn Sie keine Vonage-Bibliothek verwenden, sollten Sie sich an RFC 7519 JWT zu implementieren. JWT.io bietet eine Auswahl an Bibliotheken zur Erzeugung von JWTs in mehreren Sprachen.