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

O Kinescope permite controlar o acesso a vídeos 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, 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 tenta assistir a um vídeo, o Kinescope pergunta ao seu backend: “Este usuário pode assistir a este vídeo?”
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.

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)

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
• password (opcional) — senha para Basic Auth
• strict (opcional) — modo de verificação estrita

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

Importante: O Kinescope envia uma solicitação HTTP com JSON para sua URL (veja o exemplo abaixo). Em resposta, simplesmente retorne 200 (permitir) ou 403 (negar).

O que chega ao seu backend

Quando um usuário tenta assistir a um vídeo, o Kinescope envia JSON com contexto para sua URL de autorização:

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

Descrição dos campos:

• id — ID do vídeo sendo acessado
• token — token de autorização que você passou em drmauthtoken (por exemplo, user_id ou JWT)
• ip — endereço IP do usuário
• type — tipo de conteúdo (geralmente "video")
• user_agent — User-Agent do navegador do usuário

O que retornar na resposta

Seu backend deve retornar um destes códigos HTTP:

Para desenvolvedores: Se o seu backend estiver temporariamente indisponível (5xx), o Kinescope não conseguirá verificar o acesso. Recomendamos configurar monitoramento e recuperação rápida do serviç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 contexto do vídeo: pelo id (ID do vídeo), determine a qual curso/pacote/seção o vídeo 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_to_video(user_id, video_id) -> 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: Mapeie os vídeos para os cursos no seu sistema (por exemplo, uma tabela course_videos com os campos course_id e 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 video_id.
• 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_video(video_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 abre uma página com o player:

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 Kinescope chama seu backend — envia uma solicitação HTTP com JSON contendo:
   • o token de autorização (aquele que você passou em drmauthtoken);
   • o ID do vídeo;
   • o endereço IP e 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.
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!