Policies

As políticas (policies) são uma ferramenta para gerenciar dois aspectos do processo de recebimento e distribuição de eventos:

  1. a implementação de validações de segurança na autorização de publicadores que enviam eventos para o Events Hub;

  2. as configurações de entrega, referentes às tentativas automáticas de envio de eventos aos subscritores caso o primeiro envio falhe.

Opções de segurança

A autorização de publicadores é implementada por meio de interceptores. Há cinco interceptores disponíveis: Access Token Validation (para validar access tokens passados nas requisições); Client ID Validation (para validar client IDs passados nas requisições); OAuth Validation (para validar access tokens e client IDs passados em headers das requisições); JWT Validation (para validar tokens JWT passados nas requisições); e IP Filtering Validation (para definir listas de IPs que têm permissão ou não de enviar requisições).

Os endpoints de autorização são definidos a nível de contexto na tela Authorizations. A definição a nível de contexto significa que é possível utilizar diferentes endpoints de autorização, incluindo um mock para cenários de teste.

Para OAuth Validation, Client ID Validation e Access Token Validation, os endpoints são definidos em Authorizations  OAUTH. Para JWT Validation, em Authorizations  JWT.

É possível utilizar a Sensedia API Platform para prover a autorização aos publicadores. Criamos um tutorial para ajudá-lo a configurar os interceptores de segurança utilizando a Plataforma como servidor de autorização. Você também pode acessar o tutorial para entender melhor as diferenças entre os fluxos de validação de OAuth, Client ID e Access Token.

Configuração de tentativas automáticas de entrega

Quando a primeira tentativa de entrega de evento a um subscritor falha, o Events Hub pode tentar novamente o envio, seguindo as configurações cadastradas. Essas configurações incluem a quantidade total de tentativas que deverão ser feitas (até no máximo 10), o código de estado HTTP que deve disparar uma nova tentativa, e o timeout da requisição. Se ainda assim a entrega não for bem-sucedida, será possível fazer tentativas manuais na tela Delivery Retry.

Veja mais sobre o funcionamento das tentativas automáticas abaixo.

As políticas são criadas na tela Policies e são aplicadas a handlers no processo de criação ou edição de um handler. Só é possível aplicar uma política por handler, mas a mesma política pode ser usada por múltiplos handlers.

É possível criar um handler e não aplicar uma política a ele?

Sim, você pode criar um handler sem política aplicada e os tópicos poderão ser usados normalmente como canal de envio de eventos por publicadores. Nesse caso, além de não incluir interceptores de segurança no fluxo das requisições vindas dos publicadores, o Events Hub não fará tentativas automáticas de envio caso a primeira entrega de evento a um subscritor falhe.

Listagem de políticas

A tela Policies exibe todas as políticas já criadas, listadas em ordem alfabética:

policies

É possível pesquisar políticas pelo nome através do campo Name.

A lista de políticas exibe o nome e descrição (se houver) de cada política. A coluna DETAILS contém o ícone icon expand, que exibe as configurações da política selecionada:

policies details

A coluna ACTIONS contém ícones para editar (icon edit) e excluir (icon delete) políticas.

Criando uma política

Para criar uma nova política, clique no botão flutuante +, que levará a uma tela única de configuração:

policies create

Os dados básicos a serem informados são nome (campo Name, obrigatório) e descrição (campo Description, opcional). O nome deve ser único; ou seja, não é possível criar duas políticas com o mesmo nome. As outras duas seções dizem respeito às configurações de segurança e entrega de eventos.

Segurança

A seção HANDLER PUBLISHER SECURITY FLOW inclui os interceptores de segurança que podem ser adicionados ao fluxo. Pelo menos uma das opções deve ser selecionada, mas é possível adicionar mais de um interceptor.

Veja nosso tutorial sobre como utilizar a Sensedia API Platform para prover autorização para publicadores e mais detalhes sobre os diferentes fluxos de validação de client ID/access token.

Para incluir um interceptor, clique no ícone icon add ao lado de seu nome, o que abrirá uma tela de configuração. Estas são as opções:

  • Access Token Validation: valida um access token passado na requisição. A configuração contém os seguintes campos:

    • Location, para selecionar onde o access token será passado, com as opções: any (qualquer uma das opções, então todas serão checadas); cookie; header; header ou cookie; ou query param.

    • Name, para informar o nome com o qual o valor do access token será passado.
      policies clientid token jwt

  • Client ID Validation: valida um client ID passado na requisição. A configuração contém os seguintes campos:

    • Location, para selecionar onde o client ID será passado, com as opções: any (qualquer uma das opções, então todas serão checadas); cookie; header; header ou cookie; ou query param.

    • Name, para informar o nome com o qual o valor do client ID será passado.
      policies clientid token jwt

  • IP Filtering Validation: inclui uma lista de IPs como base para a permissão de envio de requisições, com a possibilidade de Block List (lista de IPs que terão suas requisições bloqueadas) ou Allow List (lista dos únicos IPs que poderão enviar requisições). A configuração contém os seguintes campos:

    • List Type, para selecionar o tipo da lista, se Block List ou Allow List.

    • IP List, para incluir os IPs, que devem ser separados por vírgula.
      policies ip filtering

  • OAuth Validation: valida client_id e access_token_ passados no header das requisições. A URL que provê validação deve ser incluída na página Authorizations e não há campos para cadastro.

    policies oauth

  • JWT Validation: valida token JWT (que deve ser enviado no padrão Bearer) passado na requisição. A URL que provê validação deve ser incluída na página Authorizations. A configuração contém os seguintes campos:

    • Location, para selecionar onde o token será passado, com as opções: header; default JWT header (header JWT padrão); ou query param.

    • Name, para informar o nome com o qual o valor do token será passado.
      policies clientid token jwt

Após as publicações serem recebidas pelo Events Hub, o publisher é exibido na listagem de eventos da tela Event Status. Mas, para que essa identificação ocorra, é necessário que exista um interceptor que valide client ID como parte da política aplicada ao handler (seja OAuth Validation ou Client ID Validation).

Após incluídos os interceptores, eles serão listados na sub-seção Execution Flow:

policies flow

É possível editar, apagar e reordenar os itens:

  • O ícone icon edit é usado para editar as configurações de cada interceptor.

  • O ícone icon delete é usado para remover o interceptor do fluxo.

  • É possível reordenar os interceptors clicando sobre cada um e arrastando. Cada item será executado na ordem exibida na tela e, caso a validação de um deles falhe, a requisição será abortada durante a execução.

Configurações de entrega

A seção Delivery Settings configura a distribuição de eventos para subscritores (veja mais sobre o funcionamento das tentativas automáticas abaixo).

policies retry settings

Estes são os campos para configuração, todos obrigatórios:

  • Automatic Retry Quantity: campo para definir a quantidade de tentativas automáticas que serão realizadas caso o primeiro envio falhe. É possível configurar até 10 tentativas automáticas.

  • Requisition Timeout: tempo limite de espera pelo retorno da URL do subscritor a cada tentativa de entrega.

  • Status Code For Automatic Retry: códigos de estado HTTP de retorno que devem disparar uma tentativa automática. Múltiplos códigos devem ser separados por vírgula e, para declarar a família, usamos "xx". Ex.: 400, 5xx (o último contendo todos os códigos de status da familia 500).

Edição e exclusão de políticas

Todas as configurações de uma política podem ser editadas por meio do ícone icon edit na coluna ACTIONS da tela Policies.

Na mesma coluna está o ícone para exclusão de políticas (icon delete). Note que não será possível excluir políticas que estejam em uso em um handler.

Funcionamento das tentativas automáticas de envio

Caso a primeira tentativa de entrega do evento a um subscritor falhe, o Events Hub tentará o envio novamente, repetindo a requisição até que a entrega seja bem sucedida ou que o número de tentativas automáticas cadastrado no campo Automatic Retry Quantity (descrito acima) seja atingido.

Para aumentar as chances de sucesso no envio, aplicamos o algoritmo exponential backoff (ou recuo exponencial) para disparar as tentativas sucessivas. Esse algoritmo aumenta progressivamente o tempo de atraso entre as tentativas até um limite de atraso ser atingido (no nosso caso, 10 segundos). Dessa forma, é possível evitar falhas por causa de muitas tentativas subsequentes em um contexto de tráfego de rede congestionado.

Se todas as tentativas automáticas falharem, será possível tentar envio manual na tela Delivery Retry.

Thanks for your feedback!
EDIT
How useful was this article to you?