Étape 3 : distribuer les jetons

Maintenant que vous disposez d’une scène, créez et distribuez les jetons que les clients utilisent pour la rejoindre. Chaque client a besoin d’un jeton de participant pour rejoindre une scène et envoyer ou recevoir une vidéo. Les applications qui utilisent une RealTimeConnection ont également besoin d’un jeton de connexion.

Un jeton de participant autorise un participant à rejoindre une scène spécifique et définit ses capacités de publication et d’abonnement. Un jeton de connexion autorise une connexion réseau partagée qu’un client peut réutiliser lorsqu’il passe d’une scène à l’autre dans le même compte et la même Région AWS. Un jeton de connexion ne remplace pas un jeton de participant. Le client a besoin d’un jeton de participant pour chaque scène qu’il rejoint.

Il existe deux méthodes pour générer des jetons :

Les deux méthodes sont décrites ci-dessous.

Création de jetons à l’aide d’une paire de clés

Vous pouvez créer des jetons de participant et des jetons de connexion dans votre application serveur en signant des JWT avec une paire de clés ECDSA publique/privée. Importez la clé publique dans IVS afin qu’IVS puisse vérifier la signature du JWT lorsqu’un client se connecte.

Création d’une nouvelle paire de clés

Il existe différentes méthodes pour créer une paire de clés. Ci-dessous, nous en donnons deux exemples.

Pour créer une paire de clés dans la console, procédez comme suit :

Pour créer une nouvelle paire de clés EC P384 avec OpenSSL (vous devrez peut-être d’abord installer OpenSSL), procédez comme suit. Ce processus vous permet d’accéder à la fois aux clés privées et publiques. Vous n'avez besoin de la clé publique que si vous souhaitez tester la vérification de vos jetons.

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

Importez à présent votre nouvelle clé publique à l'aide des instructions suivantes.

Importation de la clé publique

Une fois la paire de clés créée, vous pouvez importer la clé publique dans IVS. Notre système n'a pas besoin de la clé privée, mais vous l'utilisez pour signer des jetons.

Pour importer une clé publique existante avec la console :

Pour importer une clé publique existante avec la CLI :

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

Vous pouvez omettre --region <aws-region> si la région figure dans votre fichier de configuration AWS local.

Voici un exemple de réponse :

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

Requête d’API

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

Jetons de participant

Un jeton de participant autorise un participant à rejoindre une scène. Il contient l’ARN et l’ID de la scène, les points de terminaison, les attributs facultatifs du participant ainsi que les capacités de publication et d’abonnement.

Créer des jetons de participant avec une paire de clés

Pour plus d’informations sur l’utilisation des JWT et des bibliothèques prises en charge pour la signature de jetons, consultez la page jwt.io. Sur l'interface jwt.io, vous devez saisir votre clé privée pour signer les jetons. La clé publique n'est nécessaire que si vous souhaitez vérifier les jetons.

Tous les JWT présentent trois champs : header (en-tête), payload (charge utile) et signature.

Les schémas JSON de l’en-tête et des données utiles du JWT sont décrits ci-dessous. Vous pouvez également copier un modèle JSON depuis la console IVS. Pour obtenir l’en-tête et les données utiles JSON depuis la console IVS :

Schéma du jeton : en-tête

header spécifie :

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

Schéma du jeton : données utiles

Les données utiles contiennent des données spécifiques à IVS. Tous les champs sauf user_id sont obligatoires.

Schéma du jeton : signature

Pour créer la signature, utilisez la clé privée avec l’algorithme spécifié dans l’en-tête (ES384) pour signer l’en-tête encodé et la charge utile encodée.

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

Instructions

Création de jetons à l’aide de l’API de diffusion en temps réel IVS

Comme indiqué ci-dessus, une application cliente demande un jeton à votre application serveur, qui appelle CreateParticipantToken à l’aide d’un AWS SDK ou d’une demande signée avec SigV4. Étant donné que les informations d’identification AWS sont utilisées pour appeler l’API, le jeton doit être généré dans une application sécurisée côté serveur, et non dans l’application côté client.

Lors de la création d’un jeton de participant, vous pouvez éventuellement spécifier des attributs et/ou des fonctionnalités :

Pour plus de détails, voir CreateParticipantToken.

Vous pouvez créer des jetons de participant via la console ou l’interface CLI à des fins de test et de développement, mais vous souhaiterez très probablement les créer à l’aide de l’AWS SDK dans votre environnement de production.

Vous devez disposer d’un moyen de distribuer les jetons de votre serveur à chaque client (par exemple, au moyen d’une demande d’API). Nous ne proposons pas cette fonctionnalité. Pour ce guide, vous pouvez simplement copier et coller les jetons dans le code client en suivant les étapes suivantes.

Important : considérez les jetons comme opaques ; ne développez pas de fonctionnalités reposant sur leur contenu. Le format des jetons pourrait changer à l’avenir.

Instructions de la console

Instructions de la CLI

Pour créer un jeton avec l’AWS CLI, vous devez d’abord télécharger et configurer l’interface CLI sur votre machine. Pour plus de détails, consultez le ‬Guide de l'utilisateur de l'Interface de ligne de commande AWS. La génération de jetons avec l’AWS CLI convient aux tests, mais pour la production, nous vous recommandons de générer les jetons côté serveur à l’aide de l’AWS SDK (voir les instructions ci-dessous).

AWSInstructions du SDK 

Vous pouvez utiliser le SDK AWS pour créer des jetons. Vous trouverez ci-dessous les instructions concernant le SDK AWS utilisant JavaScript.

Important : ce code doit être exécuté côté serveur et sa sortie doit être transmise au client.

Prérequis : pour utiliser l’exemple de code ci-dessous, vous devez installer le package aws-sdk/client-ivs-realtime. Pour plus de détails, consultez Prise en main de l’AWS SDK pour 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);

Jetons de connexion

Un jeton de connexion est un JWT autosigné qui autorise une connexion réseau partagée. Un client peut réutiliser cette connexion lorsqu’il passe d’une scène à l’autre dans le même compte AWS et la même région, jusqu’à l’expiration du jeton.

Créez et signez des jetons de connexion sur votre serveur à l’aide de la paire de clés créée précédemment. Envoyez le jeton de connexion au client avant qu’il ne commence un flux de travail impliquant des passages d’une scène à l’autre. Le client crée une RealTimeConnection et la fournit chaque fois qu’il crée une scène. Le client utilise ensuite le jeton de participant approprié pour chaque scène qu’il rejoint.

En-tête du jeton

Utilisez l’en-tête du jeton décrit dans Créer des jetons de participant avec une paire de clés.

Données utiles du jeton

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

Les données utiles contiennent des données spécifiques à IVS. Tous les champs sont obligatoires :

Un jeton de connexion ne contient ni ARN de scène, ni ID de scène, ni point de terminaison WHIP, ni capacités de participant, ni attributs de participant, ni ID utilisateur. Ces valeurs se trouvent dans le jeton de participant de la scène que le client rejoint.

Signez le jeton comme décrit dans Créer des jetons de participant avec une paire de clés, en utilisant l’en-tête et les données utiles du jeton de connexion ci-dessus.