Tokens de acesso¶

media.access.token

Para novas integrações, use JWT de espectador. Sua aplicação verifica as permissões do espectador e obtém um token de reprodução assinado pela API de administração do central. O reprodutor apresenta esse token ao streamer, que o valida localmente sem consultar sua aplicação ou um backend HTTP de autorização.

Um mesmo JWT funciona em todos os edges do cluster que receberam a chave pública correspondente. Ao mudar para outro edge, o espectador não precisa de um token novo. Esse método de admissão elimina a carga de solicitações de autorização quando muitos espectadores começam a assistir ao mesmo tempo e remove a dependência da admissão de cada espectador em relação à disponibilidade e à latência de um backend HTTP externo.

O backend HTTP de autorização é um mecanismo legado, obsoleto e não recomendado para novas integrações. Ele permanece disponível por compatibilidade.

Como o token é enviado¶

O token pode ser enviado de duas maneiras:

• Parâmetro da URL — ?token=<token>, que tem prioridade.
• Cabeçalho — Authorization: Bearer <token>, usado quando a URL não contém o parâmetro token.

Para HLS, abra a playlist mestra com o token: o Sapsan o adiciona às URLs das playlists e dos dados de mídia aninhados. Se usar um cabeçalho, o cliente deve enviá-lo nas solicitações protegidas. Não forneça a chave de administração ao reprodutor: somente sua aplicação precisa dela para emitir JWTs.

Obter um JWT pelo central¶

Primeiro crie um stream chamado news e conecte os streamers ao central. Aguarde a entrega da configuração e das chaves públicas aos edges. O exemplo requer curl e jq; substitua os domínios e a chave de administração pelos seus valores.

CENTRAL_URL='https://central.example.com'
EDGE_1='https://edge1.example.com'
EDGE_2='https://edge2.example.com'
ADMIN_KEY='replace-with-management-api-key'

ISSUED=$(curl --fail-with-body --silent --show-error \
  -X POST "$CENTRAL_URL/central/api-v4/play-sessions/grants" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"streams":["news"],"user_id":"viewer-42","ttl_secs":3600,"max_concurrent":1}')

TOKEN=$(printf '%s' "$ISSUED" | jq -er '.token')
JTI=$(printf '%s' "$ISSUED" | jq -er '.jti')

O central cria uma concessão, um registro do acesso concedido, e retorna 201 Created. Os campos da concessão e token ficam no mesmo nível da resposta. jti identifica a concessão, e expires_at indica quando ela expira, em UTC. O JWT só é retornado na criação; consultar a concessão pela API não retorna o token.

Campos da solicitação:

Reprodução e mudança de edge¶

Obtenha a playlist HLS do primeiro edge e depois do segundo usando o mesmo TOKEN:

curl --fail-with-body --silent --show-error \
  "$EDGE_1/streaming/v/news/index.m3u8?token=$TOKEN"

curl --fail-with-body --silent --show-error \
  "$EDGE_2/streaming/v/news/index.m3u8?token=$TOKEN"

Esses comandos obtêm playlists; para reproduzir o conteúdo, abra a URL correspondente em um reprodutor HLS. Ambos os edges devem poder servir o stream news. A validação do JWT por si só não atribui o stream a uma máquina nem garante a disponibilidade da fonte.

Para que o balanceador escolha o streamer, use https://central.example.com/playback/v/news/index.m3u8?token=<JWT>. A disponibilidade dessa URL também depende do central: ele seleciona um streamer e redireciona a solicitação ou atua como proxy da mídia. Uma URL direta do edge é validada pelo próprio streamer.

Mudar de edge pode criar uma nova sessão local. O central associa as sessões à concessão e considera a atividade para que o edge anterior, que já não recebe solicitações de mídia, não ocupe o limite indefinidamente. Veja sessão do cluster e mudança de edge.

Escopo e validade¶

O listener MoQ ainda não utiliza este mecanismo de autorização.

O JWT é assinado com Ed25519 pelo algoritmo EdDSA; kid no cabeçalho seleciona a chave pública. Seu conteúdo inclui:

• jti — identificador da concessão.
• user_id — identificador do espectador.
• exp — expiração em segundos Unix.
• streams — nomes de mídia permitidos.
• bind_ip — endereço IP ou rede, se a vinculação estiver configurada.

O ao vivo e o arquivo de um stream usam o mesmo nome: news. Para VOD, informe vod/<asset-id>: a concessão cobre os arquivos desse asset independentemente do root de armazenamento e do nome do arquivo. O claim padrão aud não é usado para esse escopo. O limite max_concurrent fica no registro do central, fora do JWT.

O edge verifica localmente a assinatura, a validade e o escopo, além da vinculação a IP, se configurada. Há uma tolerância de 30 segundos para diferenças de relógio. Um JWT inválido é rejeitado sem tentativa de autorização pelo backend HTTP. Após a expiração, as próximas solicitações HTTP são rejeitadas; ampliar o acesso requer uma nova concessão. Não há garantia de interrupção imediata de uma resposta HTTP contínua já aberta; essa limitação está descrita em autorização da sessão. Planeje a renovação do token na aplicação se o espectador puder continuar assistindo depois da expiração.

Limite de sessões e revogação de acesso¶

max_concurrent se aplica à concessão em todo o cluster. O central recebe informações sobre as sessões e encerra de forma assíncrona as sessões ativas mais antigas que excedem o limite; a nova sessão permanece. Isso não rejeita imediatamente a segunda solicitação em cada edge. O limite conta sessões do servidor, não necessariamente dispositivos físicos diferentes: solicitações com a mesma mídia, IP e concessão podem ser agrupadas em uma única sessão HTTP.

Alterar o limite sem reemitir o JWT:

curl --fail-with-body --silent --show-error \
  -X PATCH "$CENTRAL_URL/central/api-v4/play-sessions/grants/$JTI" \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"max_concurrent":2}'

Revogar toda a concessão:

curl --fail-with-body --silent --show-error \
  -X DELETE "$CENTRAL_URL/central/api-v4/play-sessions/grants/$JTI" \
  -H "Authorization: Bearer $ADMIN_KEY"

A revogação retorna 204 No Content. O central a entrega aos streamers por um canal separado de terminações. Ao recebê-la, o streamer fecha as sessões dessa concessão e rejeita novas solicitações. A revogação não é uma verificação global imediata em cada solicitação de mídia: se perder a conexão com o central, o edge não saberá de uma nova revogação até o restabelecimento do canal.

Entrega de chaves e operação sem conexão com o central¶

O central mantém a chave privada de assinatura e entrega as chaves públicas aos streamers em auth.ticket_keys, junto com a configuração. Quando a política não especifica uma lista de chaves, o central insere as próprias chaves automaticamente. Um edge com uma chave pública pode validar JWTs, mas não pode emitir tokens novos.

A validação em um edge já configurado não exige que o central esteja disponível. Enquanto o JWT for válido e a mídia estiver disponível, a admissão local continua usando as chaves recebidas. Estas operações ainda dependem do central:

• Emissão de novas concessões — exige a API do central e seu armazenamento.
• Novas chaves e alterações de política — precisam chegar aos streamers.
• Revogações e limite global de sessões — exigem o canal de terminações e as informações de sessões.
• Balanceamento por /playback — é realizado pelo central.

Durante a rotação, a chave pública anterior deve continuar disponível para validar os JWTs que ainda forem válidos. Não a remova antes de esses tokens expirarem. O suporte a várias chaves não implica a existência de uma API pública de rotação automática.

Tokens estáticos¶

Os tokens estáticos permanecem disponíveis por compatibilidade e para instalações existentes simples. Eles não substituem a emissão de concessões individuais aos espectadores:

auth:
  play_tokens:
  - viewer-secret-1
  publish_tokens:
  - publisher-secret-1

• play_tokens — tokens de reprodução.
• publish_tokens — tokens de publicação.

O JWT de espectador se destina à reprodução; não o use como permissão de publicação. Em um cluster gerenciado, o central entrega a política auth; o YAML acima mostra a estrutura das configurações para um streamer independente.

opaque_tokens é true por padrão para manter a compatibilidade. Após a migração, pode defini-lo como false para desativar o caminho geral de tokens opacos e backends HTTP, incluindo os tokens estáticos da política global. Os tokens de reprodução nas configurações de cada stream continuam funcionando. Um open_playback explícito continua abrindo o acesso à reprodução. Verifique toda a política de acesso durante a migração.