Passaggio 3: Distribuisci i token

Ora che hai una fase, crea e distribuisci i token che i client usano per parteciparvi. Ogni client ha bisogno di un token di partecipazione per partecipare a una fase e inviare o ricevere video. Le applicazioni che utilizzano una RealTimeConnection hanno bisogno anche di un token di connessione.

Un token partecipante autorizza un partecipante a partecipare a una fase specifica e definisce le funzionalità di pubblicazione e iscrizione di tale partecipante. Un token di connessione autorizza una connessione di rete condivisa che un client può riutilizzare nel passaggio da una fase all’altra nello stesso account AWS e nella stessa regione. Un token di connessione non sostituisce un token partecipante. Il client ha bisogno di un token partecipante per ogni fase a cui partecipa.

Esistono due metodi per generare i token:

Entrambi gli approcci sono descritti di seguito.

Creazione di token con una coppia di chiavi

Puoi creare token partecipanti e token di connessione nella tua applicazione server firmando JWT con una coppia di chiavi pubblica/privata ECDSA. Importa la chiave pubblica in IVS in modo che IVS possa verificare la firma JWT quando un client si connette.

Creazione di una nuova coppia di chiavi

Esistono vari metodi per creare una coppia di chiavi. Di seguito, forniamo due esempi.

Per creare una nuova coppia di chiavi nella console, completa la seguente procedura:

Per creare una nuova coppia di chiavi EC P384 con OpenSSL (prima potrebbe essere necessario installare OpenSSL), completa la seguente procedura. Questo processo consente di accedere sia alla chiave privata che a quella pubblica. La chiave pubblica è necessaria solo se desideri testare la verifica dei token.

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

Ora importa la nuova chiave pubblica utilizzando le istruzioni riportate di seguito.

Importazione della chiave pubblica

Quando disponi di una coppia di chiavi, puoi importare la chiave pubblica in IVS. La chiave privata non è necessaria per il nostro sistema, ma viene utilizzata dall'utente per firmare i token.

Per importare una chiave pubblica esistente con la console:

Per importare una chiave pubblica esistente con la CLI:

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

Puoi omettere --region <aws-region> se la regione è nel tuo file di configurazione AWS locale.

Di seguito è riportata una risposta di esempio:

{
    "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": {}
    }
}

Richiesta API

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

Token partecipanti

Un token partecipante autorizza un partecipante a partecipare a una fase. Contiene l’ARN e l’ID della fase, gli endpoint, gli attributi opzionali dei partecipanti e le funzionalità di pubblicazione e iscrizione.

Crea dei token partecipante con una coppia di chiavi

Per informazioni dettagliate su come lavorare con i JWT e le librerie supportate per la firma dei token, visita jwt.io. Nell'interfaccia jwt.io, per firmare i token devi inserire la tua chiave privata. La chiave pubblica è necessaria solo se desideri verificare i token.

Tutti i JWT hanno tre campi: intestazione, payload e firma.

Gli schemi JSON per l’intestazione e il payload di JWT sono descritti di seguito. In alternativa, è possibile copiare un JSON di esempio dalla console IVS. Per ottenere l'intestazione e il payload JSON dalla console IVS:

Schema dei token: intestazione

L'Intestazione specifica:

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

Schema dei token: payload

Il payload contiene dati specifici di IVS. Tutti i campi tranne user_id sono obbligatori.

Schema dei token: firma

Per creare la firma, utilizza la chiave privata con l'algoritmo specificato nell'intestazione (ES384) per firmare l'intestazione codificata e il payload codificato.

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

Istruzioni

Creazione di token con l'API di streaming in tempo reale di IVS

Come mostrato sopra, un’applicazione client richiede un token all’applicazione server e l’applicazione server chiama CreateParticipantToken utilizzando un SDK AWS o una richiesta firmata SigV4. Poiché le credenziali AWS vengono utilizzate per chiamare l'API, il token deve essere generato in un'applicazione sicura lato server, non nell'applicazione lato client.

Quando si crea un token del partecipante, è possibile specificare attributi e/o funzionalità:

Per i dettagli, consulta CreateParticipantToken.

Puoi creare token per i partecipanti tramite la console o l’interfaccia a riga di comando per test e sviluppo, ma molto probabilmente vorrai crearli con l’SDK AWS nel tuo ambiente di produzione.

Avrai bisogno di un modo per distribuire i token dal server a ciascun client (ad esempio, tramite una richiesta API). Questa funzionalità non è disponibile. Per questa guida, puoi semplicemente copiare e incollare i token nel codice cliente come riportato nei seguenti passaggi.

Importante: tratta i token come opachi; non creare funzionalità basate sul contenuto dei token. Il formato dei token potrebbe cambiare in futuro.

Istruzioni per la console

Istruzioni per la CLI

La creazione di un token con AWS CLI richiede prima il download e la configurazione della CLI sul computer. Per maggiori dettagli, consulta la Guida per l'utente dell'interfaccia a riga di comando di AWS. Nota: la generazione di token con AWS CLI è utile per scopi di test, ma per l’uso in produzione si consiglia di generare token sul lato server con l’SDK AWS (vedere le istruzioni di seguito).

AWSIstruzioni per gli SDK 

Per creare i token, è possibile utilizzare l'SDK AWS. Di seguito sono riportate le istruzioni per l'SDK AWS che utilizza JavaScript.

Importante: questo codice deve essere eseguito sul lato server e il relativo output passato al client.

Prerequisito: per utilizzare l'esempio di codice riportato di seguito, è necessario installare il pacchetto aws-sdk/client-ivs-realtime. Per informazioni dettagliate, consulta Nozioni di base sull’SDK AWS per 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);

Token di connessione

Un token di connessione è un JWT autofirmato che autorizza una connessione di rete condivisa. Un client può riutilizzare questa connessione mentre passa da una fase all’altra nello stesso account AWS e nella stessa regione, fino alla scadenza del token.

Crea e firma i token di connessione sul tuo server con la coppia di chiavi creata in precedenza. Invia il token di connessione al client prima che inizi un flusso di lavoro che passi da una fase all’altra. Il client crea una RealTimeConnection e la fornisce ogni volta che crea una fase. Il client utilizza quindi il token partecipante appropriato per ogni fase a cui partecipa.

Intestazione del token

Usa l’intestazione del token descritta in Crea token partecipanti con una coppia di chiavi.

Payload del token

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

Il payload contiene dati specifici di IVS. Tutti i campi sono obbligatori:

Un token di connessione non contiene l’ARN della fase, l’ID della fase, l’endpoint WHIP, le funzionalità dei partecipanti, gli attributi dei partecipanti o l’ID utente. Questi valori appartengono al token partecipante per la fase a cui il client partecipa.

Firma il token come descritto in Crea dei token partecipante con una coppia di chiavi, utilizzando l’intestazione del token di connessione e il payload sopra riportati.