Etapa 3: Distribuir tokens

Agora que você tem um estágio, crie e distribua tokens que os clientes usam para participar dele. Cada cliente precisa de um token de participante para entrar em um estágio e enviar ou receber vídeos. Os aplicativos que usam RealTimeConnection também precisam de um token de conexão.

Um token de participante autoriza um participante a participar de um estágio específico e define os recursos de publicação e assinatura dele. Um token de conexão autoriza uma conexão de rede compartilhada que um cliente pode reutilizar enquanto se move entre os estágios na mesma conta e região da AWS. Um token de conexão não substitui um token de participante. O cliente precisa de um token de participante para cada estágio em que entra.

Existem duas abordagens para gerar tokens:

Ambas as abordagens são descritas a seguir.

Criar tokens com um par de chaves

Você pode criar tokens de participantes e tokens de conexão no aplicativo de servidor assinando JWTs com um par de chaves pública/privada ECDSA. Importe a chave pública para o IVS para que ele possa verificar a assinatura do JWT quando um cliente se conectar.

Criar um novo par de chaves

Existem vários métodos para criar um par de chaves. Abaixo, damos dois exemplos.

Para criar um par de chaves no console, siga estas etapas:

Para criar um novo par de chaves EC P384 com o OpenSSL (talvez seja necessário instalar o OpenSSL primeiro), siga estas etapas. Este processo permite acessar as chaves privadas e públicas. Você precisará da chave pública somente se quiser testar a verificação de seus tokens.

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

Agora importe sua nova chave pública usando as instruções abaixo.

Importar a chave pública

Caso já tenha um par de chaves, você poderá importar a chave pública para o IVS. A chave privada não é necessária para nosso sistema, mas é usada por você para assinar tokens.

Para importar uma chave pública existente com o console:

Para importar uma chave pública existente com a CLI:

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

É possível omitir --region <aws-region> se a região estiver no seu arquivo de configuração local da AWS.

Este é um exemplo de resposta:

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

Solicitações de API

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

Tokens de participante

Um token de participante autoriza um participante a fazer parte de um estágio. Ele contém o ARN e o ID do estágio, os endpoints, os atributos opcionais do participante e os recursos de publicação e assinatura.

Crie tokens de participantes com um par de chaves

Para obter detalhes sobre como trabalhar com JWTs e as bibliotecas suportadas para assinar tokens, visite jwt.io. Na interface do jwt.io, é necessário inserir sua chave privada para assinar os tokens. A chave pública será necessária somente se você quiser verificar os tokens.

Todos os JWTs têm três campos: cabeçalho, carga útil e assinatura.

Os esquemas JSON para o cabeçalho e a carga útil do JWT são descritos abaixo. Como alternativa, você pode copiar um exemplo de JSON do console do IVS. Para obter a carga útil e o cabeçalho JSON do console do IVS:

Esquema de token: cabeçalho

O cabeçalho especifica:

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

Esquema de token: carga útil

A carga útil contém dados específicos do IVS. Todos os campos, exceto user_id, são obrigatórios.

Esquema de token: assinatura

Para criar a assinatura, use a chave privada com o algoritmo especificado no cabeçalho (ES384) para assinar o cabeçalho codificado e a carga útil codificada.

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

Instruções

Criar tokens com a API de streaming em tempo real do IVS

Conforme mostrado acima, um aplicativo do cliente solicita um token ao seu aplicativo de servidor, e o aplicativo de servidor chama CreateParticipantToken usando um SDK ou uma solicitação assinada SigV4 da AWS. Como as credenciais da AWS são usadas para chamar a API, o token deve ser gerado em uma aplicação segura do lado do servidor, não na aplicação do lado do cliente.

Ao criar um token de participante, você pode opcionalmente especificar atributos e recursos:

Para obter detalhes, consulte CreateParticipantToken.

É possível criar tokens de participantes usando o console ou a CLI para teste e desenvolvimento, mas é mais provável que você queira criá-los com o SDK da AWS em seu ambiente de produção.

Você precisará de uma forma de distribuir os tokens do seu servidor para cada cliente (por exemplo, por meio de uma solicitação de API). Não fornecemos essa funcionalidade. Para este guia, você pode simplesmente copiar e colar os tokens no código do cliente nas etapas a seguir.

Importante: trate os tokens como opacos; ou seja, não desenvolva funcionalidades baseadas no conteúdo do token. O formato dos tokens poderá mudar no futuro.

Instruções do console

Instruções da CLI

A criação de um token com a CLI da AWS exige que você faça o download e configure a CLI em sua máquina primeiro. Para obter mais detalhes, consulte o Guia do usuário da AWS Command Line Interface. Observe que gerar tokens com a CLI da AWS é bom para fins de teste, mas para uso em produção, recomendamos que você gere tokens do lado do servidor com o SDK da AWS (consulte as instruções abaixo).

AWSInstruções do SDK

É possível usar o AWS SDK para criar tokens. Abaixo estão as instruções para o AWS SDK usando JavaScript.

Importante: esse código deve ser executado no lado do servidor e sua saída transferida para o cliente.

Pré-requisito: para usar o exemplo de código abaixo, é necessário instalar o pacote aws-sdk/client-ivs-realtime. Para obter mais detalhes, consulte Conceitos básicos do AWS SDK para 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);

Tokens de conexão

O token de conexão é um JWT autoassinado que autoriza uma conexão de rede compartilhada. Um cliente pode reutilizar essa conexão ao se mover entre os estágios na mesma conta e região da AWS, até que o token expire.

Crie e assine tokens de conexão no seu servidor com o par de chaves criado anteriormente. Envie o token de conexão ao cliente antes que ele comece um fluxo de trabalho que se move entre os estágios. O cliente cria um RealTimeConnection e o apresenta sempre que cria um estágio. Então, o cliente usa o token de participante apropriado para cada estágio em que ingressa.

Cabeçalho do token

Use o cabeçalho do token descrito em Como criar tokens de participantes com um par de chaves.

Carga útil do 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"
}

A carga útil contém dados específicos do IVS. Todos os campos são obrigatórios:

Um token de conexão não contém ARN de estágio, ID de estágio, endpoint WHIP, recursos do participante, atributos do participante ou ID do usuário. Esses valores pertencem ao token de participante do estágio em que o cliente ingressa.

Assine o token conforme descrito em Como criar tokens de participante com um par de chaves, usando o cabeçalho do token de conexão e a carga útil acima.