Segurança do integrador

A segurança da integração depende do seu lado tanto quanto do da owiew. Este guia reúne o que você deve garantir.

Guarde os segredos

Você tem dois segredos: o segredo do aplicativo (owa_...), que obtém tokens, e o segredo do webhook, que assina as entregas.

• Guarde-os em um cofre de segredos ou nas variáveis de ambiente do servidor. Nunca no código, no repositório, em imagem de contêiner, em log, em ferramenta de chamado ou no navegador.
• O segredo do aplicativo só é usado pelo seu backend. Aplicativo de celular, página web ou extensão não podem conter esse segredo.
• Não registre o cabeçalho Authorization nem o corpo da resposta do endpoint de token.
• Use um segredo diferente em cada ambiente.
• Rode uma varredura de segredos no repositório e no pipeline.
• A owiew mostra cada segredo uma vez. Se você o perdeu, emita outro. Ele não pode ser recuperado.

Rotacione

• Segredo do aplicativo: emita um novo, publique-o no cofre, confirme que o backend já usa o novo, revogue o antigo. Defina um prazo de validade na emissão e rotacione antes de vencer.
• Segredo do webhook: a owiew mantém o anterior por 24 horas e assina com os dois. Aceite os dois no receptor e remova o antigo depois da janela. Veja assinatura de webhook.
• Vazou? Revogue na hora, sem esperar a janela, e emita um novo. Procure no histórico do seu servidor chamadas feitas com o segredo antigo.

Verifique a assinatura de todo webhook

• Recuse qualquer entrega sem assinatura válida, antes de interpretar o corpo.
• Calcule sobre os bytes brutos do corpo.
• Compare em tempo constante.
• Confira o timestamp com tolerância de 5 minutos.
• Deduplique por X-Owiew-Delivery-Id.
• Responda 401 sem detalhes quando falhar.
• Limite o tamanho do corpo que você lê (256 KiB).

Valide o token, se você o inspecionar

O seu aplicativo só repassa o token à owiew e não precisa validá-lo. Se um componente seu valida tokens da owiew (por exemplo, um serviço próprio que aceita o mesmo formato), aplique todas as verificações abaixo. Nenhuma é opcional:

Verificação	Regra
alg	Exatamente EdDSA, por lista de permissão. Recuse none, HS256 e qualquer outro. Nunca use o alg do cabeçalho para escolher o algoritmo
kid	Presente no JWKS publicado
typ	APT
Assinatura	Confere com a chave do JWKS, antes de ler qualquer claim
iss	owiew-iam
aud	A string owiew-apps
Prazo	exp no futuro, exp - iat até 120 segundos, tolerância de 30 segundos
Claims	sub, tid, iid, scp e jti no formato esperado. Recuse claim de pessoa (e-mail, papel, permissão)

Busque o JWKS por https, com cache curto, e confira a chave de novo quando aparecer um kid desconhecido.

Minimize o acesso

• Peça só os escopos de que o aplicativo precisa. Escopo a mais assusta o administrador e aumenta o estrago em caso de vazamento.
• Peça tokens por projeto e descarte-os ao fim do uso. Eles já duram só 2 minutos.
• Use a trava de IP quando o seu backend tem IPs fixos: ela barra o uso de um segredo vazado de fora.
• Trate o url de relatorio.publicado.v1 como segredo: ele abre sem login.

Proteja o receptor

• Exponha o receptor só por https, com certificado válido e TLS 1.2 ou superior.
• Use um caminho dedicado e restrinja a rota a POST.
• Responda 2xx rápido e processe em fila.
• Nunca reaproveite a resposta do receptor para devolver dado interno.
• Registre o X-Owiew-Delivery-Id, o tipo e o resultado. Não registre o corpo se ele puder conter dado pessoal.
• Se o seu receptor encaminha dados a outros sistemas, valide o projeto_id: ele só deve processar projetos que você espera.

Dados pessoais

Se o aplicativo recebe dado pessoal, a responsabilidade pelo tratamento daquele dado passa a ser sua. Mantenha base legal, retenção e descarte conforme a LGPD, e apague o dado de um projeto quando ele desinstalar o aplicativo e pedir a remoção.

Lista de conferência

1. Segredos fora do código e do navegador.
2. Segredo do aplicativo com validade e rotina de rotação.
3. Receptor verifica assinatura, timestamp e duplicidade.
4. Token em memória, renovado antes de vencer.
5. Só os escopos necessários.
6. 401 e 403 tratados sem insistir em laço.
7. Logs sem segredo, sem token e sem dado pessoal.

Próximos passos

• Assinatura de webhook
• Modelo de acesso
• Exemplo em Node