Authentifizierung
Übersicht
JSON-Web-Tokens (JWTS) sind eine kompakte und in sich geschlossene Methode zur sicheren Übertragung von Informationen zwischen Parteien, wobei ein JSON-Objekt als Struktur dient. Diese Informationen können verifiziert und strukturiert werden, da sie digital signiert werden können.
JWTs sind ein offener Standard, formal definiert in RFC 7519und wird in einer Reihe von anderen RFCs weiter ausgebaut. Dies bietet eine solide Grundlage für die Übermittlung von Informationen zwischen einem Client und einem Server.
Ein wesentliches Merkmal von JWTs ist ihre kompakte Größe. Dadurch eignen sie sich für die Übermittlung innerhalb von URLs, POST Parameter oder HTTP-Header. Das JWT selbst ist ebenfalls als Base-64-String kodiert, sodass es sich leicht in Anwendungen aus Quellen wie Befehlszeilenanwendungen, Umgebungsdateien und über das Internet einfügen lässt.
Vonage verwendet in erster Linie JWTs für die Authentifizierung bei einer Vielzahl von APIs sowohl auf dem Front-End als auch auf dem Back-End. Die Vonage In-App Chat und Voice Client SDKund Vonage Video API verwenden beide JSON-Web-Token (JWT) zur Authentifizierung, und die Vonage Video API verwendet JWTs, um zusätzliche Client-Konfigurationen für Video-Clients zu übergeben.
Diese Token werden dann kryptografisch mit einem privaten Schlüssel signiert, der mit einem Vonage Anwendung. Dieser Signierungsprozess bietet eine sichere Möglichkeit, zu überprüfen, ob die verwendeten Token von Ihrer Anwendung stammen.
Verwendung von JWTs
Bei Vonage Video werden JWTs an zwei Stellen verwendet:
- REST-API-Aufrufe
- Video-Client-Verbindungen
In beiden Fällen werden zwar JWTs verwendet, aber die darin enthaltenen Informationen sind unterschiedlich.
REST-API-Aufrufe
Die Vonage Video API verwendet Bearer-Authentifizierung. Während die Bearer-Authentifizierung eine Erweiterung des OAuth 2.0-Authentifizierungsschemas ist, verwendet Vonage die nicht interaktive Methode der OAuth 2.0-Generation zur Erstellung eines Bearer-Tokens unter Verwendung der JWT-Struktur und Ihres privaten Schlüssels.
Beim Senden einer Anfrage an Vonage Video REST API Endpunkt, müssen Sie den Authorization Kopfzeile in folgendem Format:
Authorization: Bearer <JWT>
Informationen darüber, welche Informationen für ein REST-API-JWT-Token erforderlich sind, finden Sie unter den Abschnitt JWT-Struktur weiter unten. Alle JWT-Tokens für REST-API-Aufrufe gelten als "Root"-Tokens, was bedeutet, dass sie vollen Zugriff auf die REST-API haben. Diese Token sollten NIEMALS geteilt werden mit einem Frontend-Client.
Sie können zwar selbst ein JWT-Token generieren, aber wir haben in die SDKs integrierte Hilfsmittel sowie JWT-spezifische Wrapper, die für die Arbeit mit Vonage-APIs konzipiert sind. Die Server-SDKs generieren automatisch JWTs für jede Anfrage. Wenn Sie jedoch ein JWT für eine Funktion generieren müssen, die nicht in den SDKs enthalten ist, oder um mit Beta-Funktionen zu testen, bieten wir auch JWT-Generatoren unabhängig von den SDKs an:
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.
Die Vonage JWT JDK-Bibliothek kann verwendet werden, um ein signiertes JWT mit Ansprüchen zu erzeugen.
Die Vonage JWT JDK-Bibliothek kann verwendet werden, um ein signiertes JWT mit Ansprüchen zu erzeugen.
Die Vonage .NET SDK kann verwendet werden, um ein signiertes JWT mit Ansprüchen zu erzeugen.
Nehmen wir als Beispiel an, dass wir die folgenden Angaben in den JWT einfügen wollen:
Es gibt mehrere Möglichkeiten, ein JWT zu erzeugen.
Sie können entweder die statische Methode CreateToken über die Jwt Klasse:
Oder verwenden Sie die Methode GenerateToken in einem Jwt Instanz:
Die aktuelle Version des Vonage PHP-Server-SDK kann bei Verwendung der Keypair-Authentifizierung auch ein JWT mit den entsprechenden Angaben erstellen.
Die Vonage Python JWT-Bibliothek kann verwendet werden, um ein signiertes JWT mit Standard- oder benutzerdefinierten Angaben zu erzeugen.
Die Vonage JWT JDK-Bibliothek kann verwendet werden, um ein signiertes JWT mit Ansprüchen zu erzeugen.
Client SDK Verbindungs-Token
Client-Applikationen, die die Video API-Client-SDKs verwenden, benötigen Verbindungs-Token zu authentifizieren, wenn Verbindung mit einer Sitzung. Dies ermöglicht eine signierte und sichere Übermittlung der Verbindungsinformationen für einen bestimmten Benutzer, ohne dass ein vollständiger Zugriff auf die API erforderlich ist. Client-JWTs sind auf eine bestimmte Anwendung beschränkt, haben einen strengen Zugriffsbereich und sind nur für bestimmte Routen und HTTP-Methoden gültig. Video Client SDK-Tokens enthalten zusätzliche Informationen, um die Übergabe von Informationen an den Front-End-Client zu erleichtern.
Client Connection Tokens werden auf dem serverseitigen Teil Ihrer Anwendung generiert und dann an den Client weitergegeben. So kann das Token mit dem privaten Schlüssel der Vonage Applications sicher signiert werden. Um diesen Prozess zu vereinfachen, ist die Erstellung von Client Connection Tokens in die SDKs integriert, und wir stellen Wrapper zur Verfügung:
Wie bei den serverseitigen SDKs können Sie selbst Client-Tokens erstellen, wenn Sie einen speziellen Bedarf dafür haben. Konsultieren Sie die JWT-Struktur Abschnitt für Informationen darüber, welche zusätzlichen Informationen ein Client-Token benötigt. Jedes SDK enthält eine Hilfsmethode, um Client-Token für Sie zu erstellen:
Erstellung von JWTs
Vonage bietet eine Reihe von Möglichkeiten zur Erstellung von JWTs, die beim Testen und Debuggen nützlich sein können.
Verwendung des Vonage Server SDK
Wir empfehlen die Verwendung der Server-SDKs, um Client-seitiges Token erzeugen. Dies bietet einige zusätzliche Sicherheitsvorkehrungen und Standardwerte für die JWTs und reduziert die Erstellung der Token auf einen einzigen Aufruf. REST-API-Aufrufe erzeugen automatisch JWTs pro Anfrage, so dass ein Benutzer kein JWT erstellen muss, um auf die REST-API zuzugreifen.
Verwendung des Vonage API Online-Tools
Wenn Sie ein serverseitiges JWT zu Testzwecken erzeugen möchten, können Sie ein JWT mit unserem Online-Tool.
Geben Sie Ihren privaten Schlüssel und die Anwendungs-ID für Ihre Videoanwendung ein. Für serverseitige JWT-Tokens für Videos müssen Sie die Optionen "Sub" und "ACL" leer lassen. Das resultierende JWT kann in cURL-Befehlen oder API-Clients verwendet werden, um REST-API-Aufrufe zu testen.
Derzeit können Sie dieses Tool nicht verwenden, um Client-Verbindungstoken zu erstellen.
Verwenden der Vonage CLI
Die Vonage CLI bietet einen Befehl zur Erzeugung eines JWT. Mit der Befehlszeilenschnittstelle können Sie alle zusätzlichen Eigenschaften/Claims festlegen, die für ein JWT erforderlich sind, und JWTs programmatisch erstellen.
Um ein JWT für die Verwendung mit der REST-API zu generieren, können Sie Folgendes verwenden:
# 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 der Verwendung von vonage apps create Terminal-Befehl. Sie können diese
Informationen für die CLI speichern, indem Sie vonage auth set Befehl. Der Inhalt des privaten Schlüssels wird dann entweder in
der .vonagerc oder $HOME/.vonage/config.json Datei.
Sie können die Vonage CLI um auch Client-Verbindungs-Tokens zu erstellen. Sie müssen die zusätzliche Kundenforderungen als Teil des Befehls:
# A command with parameters
vonage jwt create `
--app-id='00000000-0000-0000-0000-000000000000' `
--private-key=./private.key `
--sub='Alice' `
--acl="{\"paths\":{\"\/*\/sessions\/**\":{}}}"
# Will produce a token
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2wiOnsicGF0aHMiOnsiLyovcnRjLyoqIjp7fSwiLyovdXNlcnMvKioiOnt9LCIvKi9jb252ZXJzYXRpb25zLyoqIjp7fSwiLyovc2Vzc2lvbnMvKioiOnt9LCIvKi9kZXZpY2VzLyoqIjp7fSwiLyovcHVzaC8qKiI6e30sIi8qL2tub2NraW5nLyoqIjp7fSwiLyovbGVncy8qKiI6e319fSwiZXhwIjoxNzQxMTgyMzA3LCJzdWIiOiJBbGljZSIsImp0aSI6Ijg1MTViNzk2LTA1YjktNGFkMS04MTRkLTE1NWZjZTQzZWM1YiIsImlhdCI6MTc0MTE4MTQwNywiYXBwbGljYXRpb25faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifQ.BscMdDXZ1-nuLtKyPJvw9tE8E8ZjJvTPJPMT9y0TjPz4Q7qqNaqxcjglc5QPtYEjh2YpZH6btSKbUF4XTClI026Hl5_QOBlnayYo7jXwhba16fa5PeyzSf30QFGFrHbANwrQJFVCjd329SZUpwK4GxgB1gf230NhbfmkhegKezqicru2WTGCKm8kQncYliFwIEYUlcRAb2c8xcaVrn_6QNNahyeJRwGFfWpIkX0Oe-S4RDlPjoq47_gYWac9MmaetB4Dd3Yp531AuniGV5JiIShkaEwuY4Zyov4Hcmajm4Lm_UFY119la7vzHis0P7cT9pPUDe5cyPj7eT8-VhitfQ
Verwendung anderer Bibliotheken
Beispiele für die Verwendung der Vonage-Bibliotheken zur Erzeugung von JWTs finden Sie unten. Wenn Sie keine der Vonage-Bibliotheken verwenden, sollten Sie sich an RFC 7519 um Ihre eigene JWT-Lösung zu implementieren. Wenn Sie das nicht tun wollen, JWT.io bietet eine Auswahl an Bibliotheken zur Erzeugung von JWTs in mehreren Sprachen.
JWT-Struktur
JWTs enthalten Informationen, die zwischen einem Client (entweder einem Videositzungs-Client oder einem Backend-Server) und den Vonage-APIs selbst ausgetauscht werden müssen. Dazu gehören Informationen, die für die Arbeit mit den REST-API-Endpunkten und Client-Servern erforderlich sind, sowie Informationen über die Gültigkeit des Tokens selbst.
Alle JWTs, die mit der Vonage Video API interagieren, haben die folgenden grundlegenden Claims bzw. Informationsschlüssel:
| Anspruch | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
application_id | Zeichenfolge | Wahr | Die ID der von Ihnen erstellten Vonage Application. |
iat | Numbers (Unix-Epochenzeit) | Wahr | "Issued at time" Dies ist der Zeitpunkt, zu dem das JWT ausgestellt wurde. |
jti | Zeichenfolge | Wahr | "JWT-ID"ein eindeutiger Bezeichner für dieses JWT. |
exp | Numbers (Unix-Epochenzeit) | Falsch | "Ablaufzeit". Dies ist der Zeitpunkt in der Zukunft, zu dem der JWT abläuft. |
Wenn die exp 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-Token für REST-API-Aufrufe
Serverseitige Token, die für REST-API-Aufrufe verwendet werden, benötigen nur diese Angaben.
Zusätzliche Ansprüche für Client Connection Tokens
So erzeugen Sie ein JWT zur Verwendung als Verbindungs-Token für einen Kunden, der eine der Video-Client-SDKsmüssen Sie zusätzliche Angaben zu den oben beschriebenen machen.
| Anspruch | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
sub | Zeichenfolge | Wahr | Das Thema. Stellen Sie dies auf video. |
acl | Zeichenfolge | Wahr | Einzelheiten finden Sie in der Zugriffskontrollliste (ACL). |
session_id | Zeichenfolge | Wahr | Die Sitzungs-ID des Videositzung. |
scope | Zeichenfolge | Wahr | Der Geltungsbereich des Tokens. Setzen Sie dies auf session.connect. |
role | Zeichenfolge | Wahr | Die Rolle des Tokens. Es kann ein Bereich von String sein Werte je nachdem, welche Berechtigungen Sie dem Client, der sich mit der Sitzung verbindet, erteilen wollen. |
data | Zeichenfolge | Falsch | Benutzerdefinierte Metadaten, die Sie hinzufügen können, um den Client zu beschreiben, der sich mit der Sitzung verbindet. Dies ist begrenzt auf 1000 Zeichen. |
initial_layout_class_list | Zeichenfolge | Falsch | Damit können Sie optional die Liste der ursprünglichen Layout-Klassen für Archive und Live-Streaming-Übertragungen für vom Kunden veröffentlichte Streams. |
Beispiel für Video Client Connect Token Payload
Zugriffskontrollliste (ACL)
Client-Verbindungs-Tokens sind begrenzt durch die acl Anspruch des Tokens. Diese ACL ist eine Liste von Pfaden, auf die das Token zugreifen darf. Unsere API lehnt jedes Token ab, auch ein erfolgreich signiertes Token, wenn es versucht, eine Route aufzurufen, die nicht in acl.paths.
Für die Zwecke der Video API müssen Sie einem Benutzer lediglich den Zugang zu /*/session/** Endpunkt, der es ihnen ermöglicht, einer Videositzung beizutreten. Es gibt noch weitere Endpunkte, die jedoch nicht mit der Video API zusammenhängen.
Beachten Sie, dass JWT-Tokens, die zum Aufrufen der REST-API verwendet werden, keine acl Anspruch.