Schritt 3: Verteilen von Token

Nachdem Sie eine Stage erstellt haben, können Sie die Tokens erstellen und verteilen, mit denen Clients ihr beitreten. Jeder Client benötigt ein Teilnehmer-Token, um einer Stage beizutreten und Videos zu senden oder zu empfangen. Anwendungen, die RealTimeConnection verwenden, benötigen ebenfalls ein Verbindungstoken.

Ein Teilnehmer-Token autorisiert eine teilnehmende Person, an einer bestimmten Stage teilzunehmen, und definiert die Veröffentlichungs- und Abonnementfunktionen dieser teilnehmenden Person. Ein Verbindungstoken autorisiert eine gemeinsam genutzte Netzwerkverbindung, die ein Client wiederverwenden kann, wenn er zwischen Stages innerhalb des gleichen AWS-Kontos und der gleichen Region wechselt. Ein Verbindungstoken ersetzt kein Teilehmer-Token. Der Client benötigt für jede Stage, der er beitritt, ein Teilnehmer-Token.

Für die Generierung von Token gibt es zwei Ansätze:

Beide Vorgehensweisen werden nachfolgend beschrieben.

Erstellen von Token mit einem Schlüsselpaar

Sie können Teilnehmer- und Verbindungstoken in Ihrer Serveranwendung erstellen, indem Sie JWTs mit einem öffentlichen/privaten ECDSA-Schlüsselpaar signieren. Importieren Sie den öffentlichen Schlüssel in IVS, damit IVS die JWT-Signatur überprüfen kann, wenn ein Client eine Verbindung herstellt.

Erstellen eines neuen Schlüsselpaares

Es gibt verschiedene Methoden, um ein Schlüsselpaar zu erstellen. Im Folgenden geben wir zwei Beispiele.

Führen Sie die folgenden Schritte aus, um in der Konsole ein neues Schlüsselpaar zu erstellen:

Um ein neues P384-EC-Schlüsselpaar mit OpenSSL zu erstellen, gehen Sie wie folgt vor (möglicherweise müssen Sie dazu zunächst OpenSSL installieren). Mit diesem Verfahren können Sie sowohl auf die privaten als auch auf die öffentlichen Schlüssel zugreifen. Den öffentlichen Schlüssel benötigen Sie nur, wenn Sie die Verifizierung Ihrer Token testen möchten.

openssl ecparam -name secp384r1 -genkey -noout -out priv.pem
openssl ec -in priv.pem -pubout -out public.pem

Importieren Sie nun den neuen öffentlichen Schlüssel. Nutzen Sie dazu die untenstehende Anleitung.

Importieren des öffentlichen Schlüssels

Sobald Sie über ein Schlüsselpaar verfügen, können Sie den öffentlichen Schlüssel in IVS importieren. Der private Schlüssel wird von unserem System nicht benötigt; er wird von Ihnen zum Signieren von Token verwendet.

So importieren Sie einen vorhandenen öffentlichen Schlüssel mit der Konsole:

So importieren Sie einen vorhandenen öffentlichen Schlüssel mit der CLI:

aws ivs-realtime import-public-key --public-key-material "`cat public.pem`" --region <aws-region>

Sie können --region <aws-region> auslassen, wenn sich die Region in Ihrer lokalen AWS-Konfigurationsdatei befindet.

Hier ist ein Beispiel für eine Antwort:

{
    "publicKey": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:public-key/f99cde61-c2b0-4df3-8941-ca7d38acca1a",
        "fingerprint": "98:0d:1a:a0:19:96:1e:ea:0a:0a:2c:9a:42:19:2b:e7",
        "publicKeyMaterial": "-----BEGIN PUBLIC KEY-----\nMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEVjYMV+P4ML6xemanCrtse/FDwsNnpYmS\nS6vRV9Wx37mjwi02hObKuCJqpj7x0lpz0bHm5v1JBvdZYAd/r2LR5aChK+/GM2Wj\nl8MG9NJIVFaw1u3bvjEjzTASSfS1BDX1\n-----END PUBLIC KEY-----\n",
        "tags": {}
    }
}

API-Anforderungen

POST /ImportPublicKey HTTP/1.1
{
  "publicKeyMaterial": "<pem file contents>"
}

Teilnehmer-Token

Ein Teilnehmer-Token autorisiert Teilnehmer, einer Stage beizutreten. Es enthält den ARN und die ID der Stage, Endpunkte, optionale Teilnehmerattribute sowie Funktionen zum Veröffentlichen und Abonnieren.

Teilnehmer-Token mit einem Schlüsselpaar erstellen

Weitere Informationen zum Arbeiten mit JWTs und den unterstützten Bibliotheken zum Signieren von Token finden Sie unter jwt.io. In der jwt.io-Oberfläche müssen Sie Ihren privaten Schlüssel eingeben, um Token zu signieren. Der öffentliche Schlüssel wird nur benötigt, wenn Sie Token verifizieren möchten.

Alle JWTs haben drei Felder: Header, Nutzlast und Signatur.

Die JSON-Schemas für den Header und die Nutzdaten des JWT werden unten beschrieben. Alternativ können Sie ein Beispiel-JSON von der IVS-Konsole kopieren. Abrufen des Headers und der Nutzdaten-JSON von der IVS-Konsole:

Token-Schema: Header

Der Header gibt Folgendes an:

{
  "alg": "ES384",
  "typ": "JWT"
  "kid": "arn:aws:ivs:123456789012:us-east-1:public-key/abcdefg12345"
}

Token-Schema: Nutzdaten

Die Nutzdaten enthalten spezifische Daten für IVS. Alle Felder außer user_id sind Pflichtfelder.

Token-Schema: Signatur

Zum Erstellen der Signatur verwenden Sie den privaten Schlüssel im Header (ES384) mit dem angegebenen Algorithmus, um den codierten Header, die codierte Nutzlast und den privaten Schlüssel zu signieren.

ECDSASHA384(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  <private-key>
)

Anleitungen

Erstellen von Token mit der IVS-Echtzeit-Streaming-API

Wie oben gezeigt, fragt eine Client-Anwendung Ihre serverseitige Anwendung nach einem Token, und die serverseitige Anwendung ruft CreateParticipantToken mithilfe eines AWS-SDK oder signierter SigV4-Anfragen auf. Da AWS-Anmeldeinformationen zum Aufrufen der API verwendet werden, sollte das Token in einer sicheren serverseitigen Anwendung generiert werden, nicht in der clientseitigen Anwendung.

Beim Erstellen eines Teilnehmer-Tokens können Sie optional Attribute und/oder Fähigkeiten angeben:

Einzelheiten finden Sie unter CreateParticipantToken.

Sie können Teilnehmer-Token über die Konsole oder CLI zu Test- und Entwicklungszwecken erstellen. Höchstwahrscheinlich möchten Sie sie jedoch mit dem AWS-SDK in Ihrer Produktionsumgebung erstellen.

Sie benötigen eine Möglichkeit, um Token von Ihrem Server an alle Clients zu verteilen (z. B. über eine API-Anforderung). Diese Funktionalität wird von uns nicht bereitgestellt. Für diese Anleitung können Sie die Token einfach kopieren und in den folgenden Schritten in den Client-Code einfügen.

Wichtig: Behandeln Sie Token als nicht transparent, entwickeln Sie keine Funktionen, die auf Tokeninhalten basieren. Das Format von Token könnte sich in Zukunft ändern.

Anleitung für die Konsole

CLI-Anweisungen

Das Erstellen eines Tokens mit der AWS-CLI erfordert, dass Sie zuerst die CLI auf Ihrem Computer herunterladen und konfigurieren. Informationen zu den ersten Schritten finden Sie im AWS-Benutzerhandbuch für die Befehlszeilenschnittstelle. Beachten Sie, dass die Generierung von Token mit der AWS-CLI für Testzwecke gut geeignet ist. Für den produktiven Einsatz empfehlen wir jedoch, Token auf der Serverseite mit dem AWS-SDK zu generieren (siehe Anweisungen unten).

AWS-SDK-Anweisungen

Sie können das AWS-SDK für die Erstellung von Tokens verwenden. Im Folgenden finden Sie Anweisungen für das AWS-SDK, das JavaScript verwendet.

Wichtig: Dieser Code muss serverseitig ausgeführt und seine Ausgabe an den Client übergeben werden.

Voraussetzung: Um das folgende Codebeispiel verwenden zu können, müssen Sie das Paket aws-sdk/client-ivs-realtime installieren. Weitere Informationen dazu finden Sie unter Erste Schritte mit dem AWS-SDK für JavaScript.

import { IVSRealTimeClient, CreateParticipantTokenCommand } from "@aws-sdk/client-ivs-realtime";

const ivsRealtimeClient = new IVSRealTimeClient({ region: 'us-west-2' });
const stageArn = 'arn:aws:ivs:us-west-2:123456789012:stage/VSWjvX5XOkU3';
const createStageTokenRequest = new CreateParticipantTokenCommand({
  stageArn,
});
const response = await ivsRealtimeClient.send(createStageTokenRequest);
console.log('token', response.participantToken.token);

Verbindungstoken

Ein Verbindungstoken ist ein selbstsigniertes JWT, das eine gemeinsam genutzte Netzwerkverbindung autorisiert. Ein Client kann diese Verbindung wiederverwenden, während er zwischen Stages innerhalb des gleichen AWS-Kontos und der gleichen Region wechselt, bis das Token abläuft.

Erstellen und signieren Sie Verbindungstoken auf Ihrem Server mit dem zuvor erstellten Schlüsselpaar. Senden Sie das Verbindungstoken an den Client, bevor dieser einen Workflow startet, der zwischen den Stages wechselt. Der Client erstellt einen RealTimeConnection und stellt ihn bei jeder Erstellung einer Stage bereit. Der Client verwendet dann das entsprechende Teilnehmer-Token für jede Stage, der er beitritt.

Token-Header

Verwenden Sie den unter Teilnehmer-Token mit einem Schlüsselpaar erstellen beschriebenen Token-Header.

Token-Nutzlast

{
    "exp": 1697322063,
    "iat": 1697149263,
    "jti": "Mx6clRRHODPy",
    "account_id": "123456789012",
    "region": "us-west-2",
    "events_url": "wss://global.events.live-video.net",
    "version": "1.0"
}

Die Nutzdaten enthalten spezifische Daten für IVS. Alle Felder sind Pflichtfelder:

Ein Verbindungstoken enthält keinen Stage-ARN, keine Stage-ID, keinen WHIP-Endpunkt, keine Teilnehmerfunktionen, keine Teilnehmerattribute und keine Benutzer-ID. Diese Werte gehören in das Teilnehmer-Token für die Stage, der der Client beitritt.

Signieren Sie das Token, wie unter Teilnehmer-Token mit einem Schlüsselpaar erstellen beschrieben, und verwenden Sie dabei den obigen Header und die Payload des Verbindungstokens.