Policies

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

  1. autorização de publicadores: as validações de segurança garantem que apenas publicadores autorizados possam enviar eventos para o Events Hub;

  2. entrega de eventos: as retentativas automáticas que o sistema deve fazer caso o primeiro envio de um evento falhe.

Listagem de políticas

A tela Policies exibe todas as políticas existentes por ordem de criação. No campo Order by você seleciona a ordenação que deseja entre:

  • Creation (desc): padrão. Lista as políticas da data de criação mais recente para a mais antiga.

  • Creation (asc): lista as políticas da data de criação mais antiga para a mais recente.

  • Name (desc): lista as políticas por ordem alfabética, do final para o começo.

  • Name (asc): lista as políticas por ordem alfabética, do começo para o final.

Você também pode buscar políticas pelo nome através do campo NAME.

A coluna DETAILS contém o ícone icon expand, que exibe as configurações da política selecionada.

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

policies details

Opções de segurança

Para autorização de publicadores, são usados interceptores. Existem cinco tipos disponíveis:

  • Access Token Validation

  • Client ID Validation

  • OAuth Validation

  • JWT Validation

  • IP Filtering Validation

Os endpoints de autorização são definidos por contexto na tela Authorizations. Nela, há duas seções:

  • OAUTH: para os interceptores OAuth Validation, Client ID Validation e Access Token Validation;

  • JWT: para o interceptor JWT Validation.

A utilização de interceptores de segurança é opcional. No entanto, se adicionar policies ao seu handler, você precisa configurar a URL do Authorization vinculado ao interceptor. Com excessão do "IP Filtering Validation", todos dependem dessa configuração para funcionar.
Se for utilizar a Sensedia API Platform para isso, veja como obter a URL de autorização.

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:

  1. número de tentativas (até 10 vezes);

  2. código de estado HTTP que aciona uma nova tentativa;

  3. tempo limite da requisição.

O Events Hub tenta reenviar novamente os eventos até obter sucesso ou atingir o número de tentativas automáticas definido nas configurações. Para aumentar as chances de entrega, usamos o algoritmo exponential backoff. Isso significa que o sistema espera um tempo cada vez maior entre as tentativas, evitando congestionamento na rede.

Se todas as tentativas automáticas falharem, você pode tentar a entrega manual através da tela Delivery Retry.

Criando uma política

Para criar uma nova política:

  1. clique no botão +;

  2. preencha Name e Description (opcional). O nome deve ser único. Não é possível criar duas políticas com o mesmo nome;

  3. Se quiser, configure opções de segurança e entrega para a política. Veja abaixo:

Segurança

A seção HANDLER PUBLISHER SECURITY FLOW inclui os interceptores de segurança que podem ser adicionados ao fluxo.

Veja como usar a Sensedia API Platform para prover a autorização de publicadores.

Escolha o interceptor que deseja aplicar clicando no ícone icon add ao lado nome do interceptor. Você pode adicionar mais de um:

  • Access Token Validation: valida um access token passado na requisição. Ao selecioná-lo, você deve informar:

    • Location: onde o access token será passado, podendo ser any (todas as opções serão selecionadas); cookie; header; header ou cookie; ou query param.

    • Name: o nome com o qual o valor do access token será passado.

  • Client ID Validation: valida um client ID passado na requisição. Ao selecioná-lo, você deve informar:

    • Location: onde o client ID será passado, podendo ser any (todas as opções serão selecionadas); cookie; header; header ou cookie; ou query param.

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

  • IP Filtering Validation: lista de IPs que podem ou não enviar requisições.

    • No campo List Type, você pode escolher entre:

      • 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.

    • IP List: para incluir os IPs. Você deve separá-los por vírgula.
      policies ip filtering

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

    policies oauth

  • JWT Validation: valida o 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. Ao selecionar este interceptor, você deve informar:

    • Location: onde o token será passado, podendo ser header; default JWT header (header JWT padrão); ou query param.

    • Name: o nome com o qual o valor do token será passado.

Os interceptores selecionados são mostrados na seção Execution Flow. Se quiser, você pode:

  • editá-los clicando no ícone icon edit;

  • desativá-los clicando no ícone desativa policy;

  • reordená-los clicando sobre o interceptor e arrastando-o para a posição desejada.
    As validações acontecerão na ordem em que aparecem na tela. Se alguma delas não der certo, a requisição é interrompida.

policies flow

Configurações de entrega

A seção Delivery Settings define o número máximo de tentativas automáticas de reenvio e os códigos de status que acionarão essas tentativas.

Configure os campos:

  • Automatic Retry Quantity: a quantidade de tentativas automáticas que serão realizadas caso o primeiro envio falhe. Permite até 10;

  • Requisition Timeout: tempo limite de espera pelo retorno da URL do subscritor a cada tentativa de entrega. Até 30 segundos;

  • Status Code For Automatic Retry: códigos de estado HTTP de retorno que devem acionar uma tentativa automática.

    • Se inserir mais de um, separe-os por vírgula.

    • Se quiser cadastrar uma família de código, use "xx": 4xx, 5xx.

    • Códigos da família 200 não são aceitos neste campo. Isso porque retornos 2xx indicam que o evento foi entregue com sucesso e não precisam ser enviados novamente.

policies retry settings

Recomendações de status codes

O campo Status Code for Automatic Retry permite a inclusão de códigos da família 400 e 500. No entanto, nem todos fazem sentido para a retentativa. Nas tabelas abaixo, detalhamos quais são recomendados e quais não:

Recomendados

Código de status

Descrição

Retentativa faz sentido?

Motivo

408

Request Timeout

Sim

O servidor não respondeu a tempo.

429

Too Many Requests

Sim

O usuário enviou muitas solicitações em um determinado período.

500

Internal Server Error

Sim

Código genérico que indica falha no servidor. Essa falha pode ocorrer por picos temporários de carga.

502

Bad Gateway

Sim

Um servidor intermediário recebeu uma resposta inválida de um servidor upstream.

503

Service Unavailable

Sim

O servidor não está pronto para processar a solicitação. Isso pode ser causado por uma manutenção ou sobrecarga.

504

Gateway Timeout

Sim

O servidor intermediário não respondeu a tempo.
Não recomendados

Código de status

Descrição

Retentativa faz sentido?

Motivo

400

Bad Request

Não

A solicitação foi mal formulada. Retentar a mesma solicitação resultará no mesmo erro.

401

Unauthorized

Não

Autenticação é necessária ou falhou. Retentar não resolverá o problema sem a autenticação adequada.

403

Forbidden

Não

O cliente não tem permissão para executar a ação. Não há motivo para retentar.

404

Not Found

Não

O recurso solicitado não foi encontrado. Retentar não trará o response esperado.
Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]