Neste guia, explicamos como gerar um token e os campos obrigatórios e opcionais para tokens.
Para criar um token, você compõe uma string para assinar, que chamamos de valor assinado neste guia. O valor assinado inclui parâmetros que descrevem o conteúdo que você está protegendo, o prazo de validade do valor assinado e assim por diante.
Use o valor assinado ao criar uma string de token. Para criar uma string de token, componha os parâmetros do token, como um código de autenticação de mensagem baseado em hash (HMAC) de chave simétrica do valor assinado.
O Media CDN usa o token composto final para ajudar a proteger seu conteúdo.
Criar um token
Crie um valor assinado concatenando uma string que contenha os campos de token obrigatórios e os campos de token opcionais desejados. Separe cada campo e todos os parâmetros com um caractere de til
~.Assine o valor assinado com uma assinatura Ed25519 ou um HMAC de chave simétrica.
Crie o token concatenando uma string que contenha os campos obrigatórios e opcionais do token. Separe cada campo e todos os parâmetros com um caractere de til
~.Ao compor o token, os valores de cada um dos parâmetros são os mesmos entre o valor assinado e a string do token, com as seguintes exceções:
FullPathHeaders
O exemplo de código a seguir mostra como criar um token de maneira programática:
Python
Para autenticar no Media CDN, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Java
Para autenticar no Media CDN, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
As seções a seguir descrevem os campos usados pelos tokens.
Campos de token obrigatórios
Os campos a seguir são obrigatórios para cada token:
Expires- Uma das seguintes opções:
PathGlobsURLPrefixFullPath
- Uma das seguintes opções:
Signaturehmac
Salvo indicação em contrário, os nomes dos parâmetros e os valores deles diferenciam maiúsculas de minúsculas.
A tabela a seguir explica cada parâmetro:
| Nome do campo / aliases | Parâmetros de token | Valor assinado |
|---|---|---|
|
Segundos inteiros decorridos desde a época Unix (1970-01-01T00:00:00Z) | Expires=EXPIRATION_TIME, após o qual o
token não é mais válido. |
|
Uma lista de até cinco segmentos de caminho para conceder acesso. Os segmentos
podem ser delimitados por vírgulas (
Os parâmetros de caminho, indicados por ponto e vírgula ( Por esses motivos, verifique se o URL não contém os seguintes
caracteres especiais: |
PathGlobs=PATHS |
URLPrefix |
Um URL codificado em base64 seguro para Web, incluindo o protocolo
Por exemplo, alguns valores de URLPrefix válidos para `https://example.com/foo/bar.ts` são `https://example.com`, `https://example.com/foo` e `https://example.com/foo/bar`. |
URLPrefix=BASE_64_URL_PREFIX |
FullPath |
Nenhuma. Ao especificar FullPath em um token, não duplique
o caminho especificado no valor assinado. Em um token, inclua o nome do campo sem um =. |
FullPath=FULL_PATH_TO_OBJECT |
Signature |
Uma versão da assinatura codificada em base64 e otimizada para a Web. | Não relevante |
hmac |
Uma versão codificada em base64 e otimizada para a Web do valor HMAC. | Não relevante |
Sintaxe de caracteres curinga PathGlobs
A tabela a seguir explica a sintaxe de caracteres curinga PathGlobs.
| Operador | Corresponde a | Exemplos |
|---|---|---|
* (asterisco) |
Corresponde a zero ou mais caracteres no caminho do URL, incluindo
barras (/).
|
|
? (ponto de interrogação) |
Corresponde a um único caractere no
caminho do URL, sem incluir caracteres de barra (/).
|
/videos/s?main.m3u8 corresponde a
/videos/s1main.m3u8. Não corresponde a
/videos/s01main.m3u8 ou /videos/s/main.m3u8.
|
Os globs precisam começar com um asterisco (*) ou uma barra (/)
para caminhos de URL.
Como * e /* correspondem a todos os caminhos do URL, não recomendamos usar nenhum deles nos tokens assinados. Para máxima proteção,
garanta que os globs correspondam ao conteúdo ao qual você quer conceder acesso.
Campos de token opcionais
Salvo indicação em contrário, os nomes dos parâmetros e os valores deles diferenciam maiúsculas de minúsculas.
A tabela a seguir explica os nomes dos parâmetros, os aliases e os detalhes dos parâmetros opcionais:
| Nome do campo / aliases | Parâmetros | Valor assinado |
|---|---|---|
|
Segundos inteiros desde a época Unix (1970-01-01T00:00:00Z) | Starts=START_TIME |
IPRanges |
Uma lista de até cinco endereços IPv4 e IPv6 no formato CIDR para
os quais esse URL é válido no formato Base64 seguro para Web. Por exemplo,
para especificar os intervalos de IP "192.6.13.13/32,193.5.64.135/32", especifique
Pode não ser útil incluir IPRanges em tokens quando os clientes estão
em risco de migrações de WAN ou em casos em que o caminho de rede para o
front-end do aplicativo é diferente do caminho de entrega.
O Media CDN rejeita clientes com um código Veja a seguir casos que podem fazer com que o Media CDN
rejeite clientes com um código
Todos esses fatores podem contribuir para que um determinado cliente tenha um
endereço IP não determinístico durante uma sessão de reprodução de vídeo. Se o
endereço IP do cliente mudar depois que você emitir o acesso e o
cliente tentar fazer o download de um segmento de vídeo no buffer de reprodução,
ele vai receber um |
IPRanges=BASE_64_IP_RANGES |
|
Uma string arbitrária, útil para análise de registros ou rastreamento de reprodução. Para evitar a criação de um token inválido, use strings codificadas em % ou em base64
seguras para a Web. Os seguintes caracteres não podem ser usados para
|
SessionID=SESSION_ID_VALUE |
|
Uma string arbitrária, útil para análise de registros. Para evitar a criação de um token inválido, use strings codificadas em % ou em base64
seguras para a Web. Os seguintes caracteres não podem ser usados para
|
data=DATA_VALUE |
Headers |
Uma lista delimitada por vírgulas de até 10 nomes de campos de cabeçalho. Os nomes de cabeçalho não diferenciam maiúsculas de minúsculas para pesquisas na solicitação. Os nomes de cabeçalho nos valores assinados diferenciam maiúsculas de minúsculas. Se um cabeçalho estiver ausente, o valor será uma string vazia. Cada cabeçalho listado em Por esse motivo, recomendamos que você assine cabeçalhos personalizados com
valores opacos, como um identificador de sessão ou de dispositivo. Evite assinar
cabeçalhos com valores que geralmente contêm vírgulas, como
|
Headers=HEADER_1_NAME=HEADER_1_EXPECTED_VALUE,
HEADER_2_NAME=HEADER_2_EXPECTED_VALUE |
Exemplos
As seções a seguir mostram exemplos de como gerar tokens.
Exemplo usando FullPath
Considere o exemplo a seguir usando o campo FullPath:
- Item solicitado:
http://example.com/tv/my-show/s01/e01/playlist.m3u8 - Data de validade: 160000000
O valor assinado é:
Expires=160000000~FullPath=/tv/my-show/s01/e01/playlist.m3u8
Para criar um token, assine o valor assinado com uma assinatura Ed25519 ou um HMAC de chave simétrica.
Veja a seguir exemplos de tokens criados com base em um valor assinado:
Assinatura Ed25519
Expires=160000000~FullPath~Signature=SIGNATURE_OF_SIGNED_VALUE
Em que SIGNATURE_OF_SIGNED_VALUE é a assinatura ED25519 do valor assinado criado anteriormente.
HMAC de chave simétrica
Expires=160000000~FullPath~hmac=HMAC_OF_SIGNED_VALUE
Em que HMAC_OF_SIGNED_VALUE é o HMAC de chave simétrica do valor assinado criado anteriormente.
Nos exemplos anteriores, FullPath é fornecido no token, mas o valor
não é repetido do caminho especificado no valor assinado. Isso permite que você
assine o caminho completo da solicitação sem duplicá-la no token.
Exemplo usando URLPrefix
Considere o exemplo a seguir usando o campo URLPrefix:
- Item solicitado:
http://example.com/tv/my-show/s01/e01/playlist.m3u8 - Data de validade: 160000000
O valor assinado é:
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4
No exemplo anterior, substituímos o caminho para o item solicitado,
http://example.com/tv/my-show/s01/e01/playlist.m3u8, pelo caminho para o item
no formato Base64 seguro para Web,
aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4.
Para criar um token, assine o valor assinado com uma assinatura Ed25519 ou um HMAC de chave simétrica.
Veja a seguir exemplos de tokens criados com base em um valor assinado:
Assinatura Ed25519
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4~Signature=SIGNATURE_OF_SIGNED_VALUE
Em que SIGNATURE_OF_SIGNED_VALUE é a assinatura ED25519 do valor assinado criado anteriormente.
HMAC de chave simétrica
Expires=160000000~URLPrefix=aHR0cDovL2V4YW1wbGUuY29tL3R2L215LXNob3cvczAxL2UwMS9wbGF5bGlzdC5tM3U4~hmac=HMAC_OF_SIGNED_VALUE
Em que HMAC_OF_SIGNED_VALUE é o HMAC de chave simétrica do valor assinado criado anteriormente.
Exemplo usando Headers
Considere o exemplo a seguir usando o campo Headers:
- Item solicitado:
http://example.com/tv/my-show/s01/e01/playlist.m3u8 - Data de validade: 160000000
- Valor de PathGlobs:
* - Cabeçalhos da solicitação esperados:
x-session-id: abcd1234x-client-version: 5.2.0
O valor assinado é:
Expires=160000000~PathGlobs=*~Headers=x-session-id=abcd1234,x-client-version=5.2.0
Para criar um token, assine o valor assinado com uma assinatura Ed25519 ou um HMAC de chave simétrica.
Veja a seguir exemplos de tokens criados com base em um valor assinado:
Assinatura Ed25519
Expires=160000000~PathGlobs=*~Headers=x-session-id,x-client-version~Signature=SIGNATURE_OF_SIGNED_VALUE
Em que SIGNATURE_OF_SIGNED_VALUE é a assinatura ED25519 do valor assinado criado anteriormente.
HMAC de chave simétrica
Expires=160000000~PathGlobs=*~Headers=x-session-id,x-client-version~hmac=HMAC_OF_SIGNED_VALUE
Em que HMAC_OF_SIGNED_VALUE é o HMAC de chave simétrica do valor assinado criado anteriormente.
Nos exemplos anteriores, Headers=x-session-id,x-client-version é fornecido no token, mas os valores de cabeçalho esperados não são repetidos do valor assinado. Isso permite assinar pares de chave-valor específicos do cabeçalho da solicitação sem
duplicar os valores no token.