Validação de ponto de extremidade com o esquema CloudEvents

Webhooks são uma dentre várias maneiras de receber eventos da Grade de Eventos do Azure. Quando um novo evento está pronto, o serviço Grade de Eventos faz o POST de uma solicitação HTTP para o ponto de extremidade configurado com as informações do evento no corpo da solicitação.

Como muitos outros serviços que dão suporte a webhooks, a Grade de Eventos do Azure exige que você comprovar a "propriedade" de seu ponto de extremidade do Webhook antes de começar a entrega de eventos para esse ponto de extremidade. Esse requisito impede que um usuário mal-intencionado inunde seu ponto de extremidade com eventos.

Validação de ponto de extremidade com CloudEvents v 1.0

CloudEvents v1.0 implementa sua própria semântica de proteção contra abusos usando o método HTTP OPTIONS. Ao usar o esquema CloudEvents para saída, a Grade de Eventos usa com a proteção de abuso do CloudEvents v1.0 em vez do mecanismo de evento de validação da Grade de Eventos.

Proteção contra abuso do CloudEvent v1.0

Qualquer sistema que permita o registro e a entrega de notificações para pontos de extremidade HTTP arbitrários pode potencialmente ser abusado, de modo que alguém registra de maneira mal-intencionada ou inadvertidamente o endereço de um sistema que não espera essas solicitações e para o qual a parte registradora não está autorizada a executar esse registro. Em casos extremos, uma infraestrutura de notificação pode ser abusada para iniciar ataques de negação de serviço contra um site arbitrário.

Para proteger o remetente de ser abusado de tal forma, um destino de entrega legítimo precisa indicar que concorda com as notificações que estão sendo entregues a ele.

Chegar ao contrato de entrega é realizado usando o handshake de validação a seguir. O handshake pode ser executado imediatamente no momento do registro ou como uma solicitação de "simulação" imediatamente antes de uma entrega.

É importante entender que o handshake não visa estabelecer um contexto de autenticação ou autorização. Ele serve apenas para proteger o remetente de ser instruído a enviar para um destino que não está esperando o tráfego. Embora essa especificação determine o uso de um modelo de autorização, esse mandato não será suficiente para proteger qualquer site arbitrário contra tráfego indesejado se esse site não implementar o controle de acesso e, portanto, ignorar o cabeçalho Authorization.

Os destinos de entrega DEVEM dar suporte ao recurso de proteção contra abusos. Se um destino não der suporte ao recurso, o remetente PODERÁ optar por não enviar para o destino ou enviar apenas a uma taxa de solicitação muito baixa.

Solicitação de validação

A solicitação de validação usa o método HTTP OPTIONS. A solicitação é direcionada para o URI de destino exato do recurso que está sendo registrado. Com a solicitação de validação, o remetente solicita ao destino permissão para enviar notificações e pode declarar uma taxa de solicitação desejada (solicitações por minuto). O destino de entrega responderá com uma instrução de permissão e a taxa de solicitação permitida. Aqui estão alguns dos campos de cabeçalho para inclusão na solicitação de validação.

WebHook-Request-Origin

O cabeçalho WebHook-Request-Origin DEVE ser incluído na solicitação de validação e solicita permissão para enviar notificações desse remetente e contém uma expressão DNS (Sistema de Nomes de Domínio) que identifica o sistema de envio, por exemplo eventemitter.example.com. O valor destina-se a identificar sumariamente todas as instâncias de remetente que atuam em nome de um determinado sistema e não de um host individual.

Após o handshake e se a permissão tiver sido concedida, o remetente DEVERÁ usar o cabeçalho de solicitação Origin para cada solicitação de entrega, com o valor correspondente ao desse cabeçalho.

Exemplo:

WebHook-Request-Origin: eventemitter.example.com

Resposta de validação

Se e somente se o destino de entrega permitir a entrega dos eventos, ele DEVERÁ responder à solicitação incluindo os cabeçalhos WebHook-Allowed-Origin e WebHook-Allowed-Rate. Se o destino de entrega optar por conceder permissão por retorno de chamada, ele reterá os cabeçalhos de resposta.

Se o destino de entrega não permite a entrega dos eventos ou não espera a entrega de eventos e, no entanto, lida com o método HTTP OPTIONS, a resposta existente não deve ser interpretada como consentimento e, portanto, o handshake não pode contar com códigos de status. Se o destino de entrega não manipular o método HTTP OPTIONS, ele DEVERÁ responder com o código de status HTTP 405, como se opções não fossem compatíveis.

A resposta de OPTIONS DEVE incluir o cabeçalho Allow que indica o método POST que está sendo permitido. Outros métodos PODEM ser permitidos no recurso, mas sua função está fora do escopo dessa especificação.

WebHook-Allowed-Origin

O cabeçalho WebHook-Allowed-Origin DEVE ser retornado quando o destino de entrega concordar com a entrega de notificação pelo serviço de origem. Seu valor DEVE ser o nome de origem fornecido no cabeçalho WebHook-Request-Origin ou um caractere de asterisco singular ('*'), indicando que o destino de entrega dá suporte a notificações de todas as origens.

WebHook-Allowed-Origin: eventemitter.example.com

Ou

WebHook-Request-Origin: *

Conteúdo relacionado

Consulte o seguinte artigo para saber como solucionar problemas de validações de assinatura de evento: Solucionar problemas de validações de assinatura de evento.