Backend de Autorização: Controle de Acesso a Vídeos pelas Regras do Seu Sistema

O Kinescope permite controlar o acesso a vídeos e streams por meio de um backend de autorização externo. Isso significa que você decide quem pode assistir a um vídeo específico — com base nas regras do seu sistema (cursos, assinaturas, funções, etc.).

Para quem é este artigo

• Desenvolvedores de LMS — precisam controlar o acesso a vídeos por curso e lição
• Proprietários de plataformas de assinatura — precisam restringir o acesso com base no status da assinatura
• Administradores de sistemas corporativos — precisam configurar o acesso por função e grupo
• Desenvolvedores backend — precisam integrar um sistema de controle de acesso com o Kinescope

Quando você precisa de um backend de autorização

Aqui estão situações típicas onde isso é útil:

• Acesso a parte da biblioteca de vídeos: um usuário comprou um curso ou pacote, mas não tem acesso à biblioteca completa.
• Assinatura: os vídeos só são acessíveis enquanto a assinatura está ativa (ou o período de teste não expirou).
• Compras individuais de lições: acesso apenas a vídeos específicos pelos quais o usuário pagou.
• Acesso corporativo: acesso por função organizacional (funcionários, parceiros) ou associação a grupo.
• Restrições contextuais: acesso por IP (IPv4, com precisão de sub-rede /24), geolocalização, janela de tempo, dispositivo ou sessão.

Se pelo menos um desses cenários se aplica a você — continue lendo. Abaixo está como configurar a verificação de acesso em dois passos.

Como funciona a verificação de acesso (4 passos)

1. Você passa um identificador de usuário para o player do Kinescope.
2. Quando um usuário inicia a reprodução de um vídeo ou de um stream, o Kinescope pergunta ao seu backend: “Este usuário pode assistir a isto?”
3. Seu backend verifica as regras (curso, assinatura, função, etc.) e responde: 200 (permitir) ou 403 (negar).
4. O player abre ou bloqueia o acesso.

Agora vamos ver como configurar isso.

Configuração: passo 1 — passando um identificador de usuário

Ao incorporar o player em um site, passe o token de autorização via parâmetro drmauthtoken na URL:

<iframe
  src="https://kinescope.io/embed/pcFNnQGsD59CMKte2SQQaz?drmauthtoken=${user_id}"
  width="640"
  height="360"
  frameborder="0"
  allow="autoplay; fullscreen; picture-in-picture; encrypted-media;"
></iframe>

Você pode usar qualquer string como token: user_id, um token JWT ou outro identificador que seu backend possa verificar. O valor de drmauthtoken chega ao seu backend sem alterações, no campo token. Se o parâmetro não for passado, token contém uma string vazia.

Recomendação (segurança): Para produção, recomendamos usar um JWT assinado em drmauthtoken. Isso protege contra substituição de token no cliente. No backend, valide a assinatura JWT e extraia o user_id.

Para desenvolvedores: Ao validar um JWT, verifique os campos padrão: exp (expiração), aud (público), iss (emissor) — isso melhora a segurança.

Configuração: passo 2 — conectando seu backend

Para que o Kinescope possa chamar seu backend para verificar o acesso, adicione a URL do seu endpoint nas configurações do projeto ou workspace via API do Kinescope.

Importante: O token de API no cabeçalho Authorization: Bearer deve estar no formato UUID. Você pode obter um token no Dashboard do Kinescope em Configurações → Tokens de API. Saiba mais sobre autorização e tratamento de erros nas regras gerais da API.

O DRM pode ser configurado em dois níveis:

• Workspace — aplica-se a todos os projetos
• Projeto — aplica-se a um projeto específico (substitui as configurações do workspace)

Para verificar o acesso, o Kinescope usa as configurações do projeto em que está o vídeo ou o stream. Se o projeto não tiver configurações, valem as do workspace.

Configurando a URL do backend de autorização via API:

Para todo o workspace:

curl -X PUT "https://api.kinescope.io/v1/drm/auth" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/drm/authorize",
    "username": "drm_user",
    "password": "drm_password",
    "strict": false
}'

Para um projeto específico:

curl -X PUT "https://api.kinescope.io/v1/drm/auth/${PROJECT_ID}" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/drm/authorize",
    "username": "drm_user",
    "password": "drm_password",
    "strict": false
}'

Parâmetros da solicitação:

• url (obrigatório) — URL do seu endpoint de verificação de acesso (para onde o Kinescope enviará solicitações durante a reprodução)
• username (opcional) — nome de usuário para Basic Auth para o seu serviço. Se o nome de usuário estiver definido, o Kinescope envia o nome de usuário e a senha no cabeçalho Authorization: Basic. Se não estiver, a solicitação é enviada sem esse cabeçalho
• password (opcional) — senha para Basic Auth
• strict (opcional) — modo estrito. true — só é possível assistir após uma resposta 200. false — apenas a resposta 403 bloqueia a exibição; erros e a indisponibilidade do seu backend não impedem a reprodução. Veja Modo estrito e não estrito

Verificando as configurações atuais:

# Para workspace
curl -X GET "https://api.kinescope.io/v1/drm/auth" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}"

# Para projeto
curl -X GET "https://api.kinescope.io/v1/drm/auth/${PROJECT_ID}" \
  -H "Authorization: Bearer ${KINESCOPE_API_TOKEN}"

Todos os métodos de configuração estão descritos na referência da API.

Importante: O Kinescope envia uma solicitação POST com JSON para sua URL (formato da solicitação). O acesso é decidido pelo código HTTP da resposta: 200 para permitir, 403 para negar. O corpo da resposta é ignorado.

O que chega ao seu backend

O Kinescope envia uma solicitação POST para sua URL de autorização sempre que o player solicita uma licença para a reprodução:

• no início da reprodução — 1–2 solicitações;
• na rotação de chaves durante a transmissão ao vivo;
• quando o player solicita a licença novamente.

As respostas não são armazenadas em cache, e a solicitação não é repetida após um timeout ou um erro: uma tentativa por solicitação de licença. Planeje a carga do seu backend pelo número de solicitações de licença, não pelo número de espectadores.

Exemplo de solicitação:

POST /drm/authorize HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Basic ZHJtX3VzZXI6ZHJtX3Bhc3N3b3Jk

{
  "id": "7127f2d7-0e96-40d0-9a03-2e987c096466",
  "ip": "11.22.33.0",
  "type": "vod",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
}

Cabeçalhos:

• Content-Type: application/json — o corpo da solicitação está em JSON
• Authorization: Basic … — o nome de usuário e a senha (username, password) das configurações de autorização. O cabeçalho só existe se o nome de usuário estiver definido

Campos do corpo da solicitação:

A solicitação não tem o campo video_id: o ID do vídeo ou o id do evento chega no campo id.

Se as suas regras de acesso também precisam funcionar para espectadores com IPv6, baseie-as nos campos token, id e user_agent, e não em ip.

Streams e suas gravações

Para a transmissão ao vivo, a solicitação só é enviada para streams com criptografia ativada — com o parâmetro protected: true (Create event). As solicitações durante a transmissão e para a gravação são diferentes:

Exemplo de solicitação durante a transmissão:

{
  "id": "0d5e8f8a-4b7c-4e61-9a3f-2c1b7d9e6a54",
  "ip": "11.22.33.0",
  "type": "live",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 ..."
}

Um evento recorrente tem várias gravações — uma por transmissão. Se a transmissão não foi gravada, o video_id no webhook live.finished é um UUID nulo.

O que retornar na resposta

O Kinescope decide apenas pelo código HTTP da resposta; o corpo da resposta é ignorado. O Kinescope aguarda a resposta por 5 segundos, nos dois modos. Se a exibição for permitida, o Kinescope emite a chave de descriptografia e o player inicia a reprodução. O que acontece com cada resposta depende do parâmetro strict:

Modo estrito e não estrito

• Estrito (strict: true) — só é possível assistir se o seu backend responder com 200. Qualquer outro código ou a falta de resposta em 5 segundos significa negação.
• Não estrito (strict: false) — apenas a resposta 403 bloqueia a exibição. Outros códigos, a falta de resposta em 5 segundos e a indisponibilidade do seu backend não impedem a reprodução.

Para desenvolvedores: Para negar a exibição com garantia, retorne exatamente 403 — no modo não estrito, 401, 404 e 5xx permitem a exibição.

Como verificar o acesso (esquema mínimo)

Aqui está o que você precisa fazer no seu manipulador de autorização:

1. Extraia user_id do token: se você usa JWT — valide a assinatura e extraia user_id; se você passa user_id diretamente — basta usá-lo.
2. Identifique o que o usuário está assistindo: pelo id e pelo type, determine a qual curso/pacote/seção o vídeo ou o stream pertence.
3. Verifique as permissões no seu sistema: o usuário tem acesso (compra, assinatura, função, grupo, etc.).
4. Retorne uma resposta: 200 se o acesso for concedido, caso contrário 403.

Em pseudocódigo resumido:

user_id = verify_and_extract_user_id(token)
if user_id is empty -> 403

if user_has_access(user_id, id, type) -> 200
else -> 403

Exemplo: acesso apenas a um curso comprado

Digamos que seu site tenha cursos e um usuário comprou apenas um deles. Como verificar o acesso a um vídeo nesse curso?

Passo 1: Associe o conteúdo do Kinescope aos cursos no seu sistema (por exemplo, uma tabela course_videos com os campos course_id e kinescope_id). Se o curso inclui streams, adicione o id do evento — retornado por Create event e Get event — e o ID do vídeo da gravação de cada transmissão: o webhook live.finished o envia no campo video_id.

Passo 2: No seu manipulador de autorização:

• Extraia user_id do token (valide o JWT se você o utilizar).
• Encontre course_id pelo id da solicitação.
• Verifique se o usuário está matriculado no curso, pagou e o curso está ativo.
• Retorne 200 se todas as verificações passarem, caso contrário 403.

Pseudocódigo:

course_id = find_course_by_kinescope_id(id)
if course_id is empty -> 403

if enrollment_is_active(user_id, course_id) -> 200
else -> 403

Como funciona (em detalhes)

Aqui está o que acontece quando um usuário assiste a um vídeo:

1. O usuário abre a página — seu site passa o token de autorização (por exemplo, user_id ou JWT) para o player do Kinescope via parâmetro drmauthtoken.
2. O player solicita uma licença — no início da reprodução, não ao abrir a página. O Kinescope envia ao seu backend uma solicitação POST com JSON contendo:
   • o token de autorização (aquele que você passou em drmauthtoken);
   • o ID e o tipo do conteúdo: vídeo (vod) ou transmissão ao vivo (live);
   • o endereço IP (IPv4 com máscara /24) e o User-Agent do usuário.
3. Seu backend verifica o acesso — revisa as regras no seu sistema (curso, assinatura, função, etc.) e retorna uma resposta:
   • HTTP 200 — acesso concedido, o servidor de licença emite uma chave de descriptografia, o vídeo fica disponível.
   • HTTP 403 — acesso negado, o vídeo não reproduz.
   • Outro código ou nenhuma resposta em 5 segundos — o resultado depende do modo strict.
4. O player recebe a resposta — abre ou bloqueia o acesso ao vídeo.

Pronto! Agora você pode controlar o acesso a vídeos usando qualquer regra do seu sistema.

O que fazer a seguir?

Após configurar o backend de autorização, recomendamos:

1. Criptografia DRM de arquivos — proteção adicional de conteúdo
2. Restrições de acesso ao vídeo — outras formas de restringir o acesso
3. Regras gerais da API — autorização e formato de solicitação

Ainda tem dúvidas? Escreva para o chat de suporte na interface do Kinescope — nossos especialistas vão ajudar!