Subscribers - Segurança e Chaves

Assinatura do subscritor

Todas as requisições feitas para os subscritores de eventos são assinadas por um mecanismo que permite aos subscritores a verificação da procedência da mensagem. A assinatura é um token gerado pelo Sensedia Events Hub a partir de uma chave de conhecimento mútuo (entre o Events Hub e o subscritor) que é enviada durante o cadastro de subscritores (veja sobre o envio abaixo).

A assinatura gerada será um JWT (JSON Web Token) com o algoritmo HS256 (HMAC com SHA-256), feita com os seguintes valores:

Campos:

• iss: o customerName.

• sub: o subscriberId.

• jti: o transactionId.

• c_hash: o conteúdo do corpo em SHA-256.

• iat: o timestamp do envio no fuso horário UTC.

Chave de assinatura

Uma chave de conhecimento mútuo deve ser informada na criação de um subscritor no Events Hub (veja sobre a criação de subscritores aqui). A subscrição em eventos só é possível após inserir a chave no campo Key e clicar em VALIDATE KEY.

NOTE

Caso a chave não seja informada dentro do tempo, clique no ícone (que aparecerá na tela) para reiniciar a contagem do tempo. Uma vez validada, a chave fica armazenada de forma segura e não pode ser recuperada.

Token JWT

O subscritor sempre receberá a assinatura em um header de requisição identificado por x-CLIENTE-webhooks-signature, sendo o conteúdo trafegado sempre em Base64 (independe de ele usá-la ou não para verificação ou se optar por utilizar mecanismos de segurança disponíveis abaixo neste documento). Ou seja, o Events Hub sempre irá trafegar a assinatura nas requisições aos subscritores, como neste exemplo de header:

O usuário pode validar a assinatura JWT em seu código. No exemplo abaixo, usamos Java:

Opções de tokens de segurança

Além da assinatura, que é sempre trafegada, o Events Hub disponibiliza também a opção de envio de um token para requisitos de segurança dos receptores dos eventos.

Após o subscritor ter cadastrado sua chave mútua para a geração da assinatura, ele pode optar por receber suas requisições com a adição de um token. Há duas opções de token: estático e dinâmico (sendo que o primeiro não expira e o segundo sim). Ambos deverão ser tokens hash em formato SHA-256 e em Base64.

Em ambos os casos, o subscritor também contará com a chave de assinatura para a validação e garantia da requisição. Se o token for configurado para ser trafegado no header, tanto a assinatura quanto o token estarão presentes (o token sob o nome configurado pelo usuário, que no exemplo abaixo é security-token):

NOTE

Você pode configurar apenas um token por subscritor.

Token estático

Ao optar por receber suas requisições adicionando um token estático (que não expira), ele pode ser cadastrado diretamente no Events Hub. É necessário informar o valor do token que será trafegado em todas as requisições.

Vale ressaltar que essa é a abordagem mais simples e que requer menos recursos e codificação do lado do subscritor (em comparação ao token dinâmico). No entanto, é mais suscetível a ataques (como um simples ataque de repetição, por exemplo).

O token deve ser configurado na etapa SECURITY de cadastro ou edição de um subscritor, por meio dos seguintes campos:

• Type: tipo do token (escolher Static).

• Location: onde o token deverá ser passado na requisição (opções: header ou query param).

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

• Token SHA-256: valor do token. Se desejar, é possível gerar um token randômico pelo ícone .

Token dinâmico

O token dinâmico oferece maior segurança no tráfego de mensagens entre o Events Hub e os subscritores em relação ao token estático.
O token dinâmico tem um período de expiração e é totalmente gerenciado pelo subscritor.

Quando tokens dinâmicos são utilizados, o subscritor terá que dispor de mais recursos e ficará com boa parte da responsabilidade de uptime do ecossistema. Isso porque o Events Hub será totalmente dependente do subscritor para obter os tokens, o que pode causar o não recebimento de mensagens. Contudo, o dinamismo do mecanismo dificulta possíveis ataques, configurando-se como uma opção mais segura.

Optando por essa abordagem, o subscritor necessariamente terá que disponibilizar uma interface para que o Events Hub obtenha o token. Essa interface deverá prover um HTTP POST que será responsável por gerar os tokens.

NOTE

Nessa abordagem, o subscritor sempre deve validar a assinatura que será trafegada também na requisição de token pelo Events Hub.

Requisição do token:

Resposta do token:

O token deve ser configurado na etapa SECURITY de cadastro ou edição de um subscritor, por meio dos seguintes campos:

• Type: tipo do token (escolher Dynamic).

• Location: onde o token deverá ser passado na requisição (opções: header ou query param).

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

• URL OAuth: URL de geração do valor do token.

NOTE

Não há refresh dos tokens dinâmicos cadastrados. Os tokens são reutilizados durante o tempo definido pelo usuário.