Tutorial: Como usar a Sensedia API Platform para Autorização dos Publicadores

O Events Hub permite com que você utilize um servidor externo para validar client ID e/ou tokens de acesso dos publicadores, permitindo com que eles enviem requisições ao Events Hub. Uma das opções é utilizar a Sensedia API Platform para fazer essa validação. Nas seções abaixo, detalhamos como usar os interceptores OAuth Validation, Client ID Validation, Access Token Validation e JWT Validation utilizando a Sensedia API Platform para prover a autorização de publicadores. Esses interceptores são configurados em políticas aplicadas a handlers.

Para todos os interceptores mencionados, utilizaremos uma API implantada na Sensedia API Platform para a autorização, chamada API Events Hub Authorization. Portanto, o endpoint que deve ser cadastrado na tela Authorizations é o endereço da API implantada na Plataforma do cliente (o endereço varia segundo o cliente) — tanto na seção OAUTH quanto na seção JWT.

O endpoint cadastrado na seção OAUTH valida as credenciais dos publicadores quando são utilizados os interceptores OAuth Validation, Client ID Validation ou Access Token Validation.

O endpoint cadastrado na seção JWT valida o token do publicador quando é utilizado o interceptor JWT Validation.

Também para todos os interceptors, o requerimento é ter uma app criada na Sensedia API Platform que deverá ser também cadastrada como publicadora na tela Publishers — inclusive, é possível importar uma app da Plataforma como opção de registro de publicador. Na Plataforma, essa app deve ter acesso à API Events Hub Authorization por meio de um plano. Veja mais sobre o registro de apps na Plataforma aqui e sobre planos aqui.

As requisições para obtenção dos tokens que devem ser passados pelos publicadores quando enviarem eventos para o Events Hub dependem do interceptor e fluxo de geração de token escolhido. Veja detalhes abaixo.

Client ID Validation

O interceptor Client ID Validation requer uma validação simples de client ID. Para isso, é necessário apenas que a app cadastrada na Plataforma tenha acesso à API Events Hub Authorization por meio de um plano e que exista um publicador no Events Hub com o mesmo client ID da app.

Ao cadastrar o interceptor na política desejada, é necessário incluir o nome sob o qual o valor do client ID será passado (por exemplo: client_id) e o local em que ele será passado na requisição (cookie; header; header ou cookie; query param; ou qualquer localização). Quando o publicador enviar um evento ao Events Hub, deve informar o client ID. Se ele for igual ao client ID cadastrado para o publicador no Events Hub e para a app na Sensedia API Platform, ele será validado.

Access Token Validation

O interceptor Access Token Validation requer a validação de um access token que deve ser obtido por algum fluxo de OAuth, à escolha do publicador.

Ao cadastrar o interceptor na política desejada, é necessário incluir o nome sob o qual o valor do access token será passado (por exemplo: access_token) e o local em que ele será passado na requisição (cookie; header; header ou cookie; query param; ou qualquer localização).

Com uma app criada na Sensedia API Platform e com acesso à API Events Hub Authorization, utilizaremos as credenciais dessa app para a obtenção de um access token, que deverá depois ser passado pelos publicadores quando enviarem eventos ao Events Hub.

Para obtenção do token, deve ser feita uma requisição à API OAuth implantada na Plataforma do cliente. Ela deve ser uma requisição POST para o endpoint <url-do-gateway>/oauth/access-token.

As informações a serem passadas na requisição dependem do fluxo escolhido para a obtenção do token. Você pode ler mais a respeito dos fluxos disponíveis e requisições necessárias aqui. No exemplo abaixo, estamos utilizando o fluxo Client Credentials.

O header deve conter as seguintes informações:

Authorization : Basic client_id:client_secret

Esse client_id:client_secret deve ser uma string convertida em Base64, usando os dados da app registrada na Plataforma.

Exemplo de header com o client_id e o client_secret convertidos para Base64:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

No corpo, deve ser passado o grant_type no formato x-www-form-urlencoded. Como estamos utilizando o Client Credentials, este deve ser o corpo:

"grant_type": "client_credentials"

O access token será gerado e deverá ser retornado como no exemplo abaixo:

{
  "access_token": "6c164a82-84a6-3bc4-8122-f777121a4f62",
  "token_type": "access_token",
  "expires_in": 3600
}

Quando o publicador enviar um evento ao Events Hub, deve passar o access token recebido na requisição, seguindo a configuração do interceptor na política.

OAuth Validation

O interceptor OAuth Validation requer a validação de um client ID e um access token que deve ser obtido por algum fluxo OAuth, à escolha do publicador.

Ao incluir o interceptor na política desejada, não é necessário fazer nenhuma configuração. Ele esperará que client_id e access_token sejam passados pelos publicadores no header das requisições.

Com uma app criada na Sensedia API Platform e com acesso à API Events Hub Authorization, utilizaremos as credenciais dessa app para a obtenção de um access token, que deverá depois ser passado pelos publicadores quando enviarem eventos ao Events Hub.

Para obtenção do token, deve ser feita uma requisição à API OAuth implantada na Plataforma do cliente. Ela deve ser uma requisição POST para o endpoint <url-do-gateway>/oauth/access-token.

As informações a serem passadas na requisição dependem do fluxo escolhido para a obtenção do token. Você pode ler mais a respeito dos fluxos disponíveis e requisições necessárias aqui. No exemplo abaixo, estamos utilizando o fluxo Client Credentials.

O header deve conter as seguintes informações:

Authorization : Basic client_id:client_secret

Esse client_id:client_secret deve ser uma string convertida em Base64, usando os dados da app registrada na Plataforma.

Exemplo de header com o client_id e o client_secret convertidos para Base64:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

No corpo, deve ser passado o grant_type no formato x-www-form-urlencoded. Como estamos utilizando o Client Credentials, este deve ser o corpo:

"grant_type": "client_credentials"

O access token será gerado e deverá ser retornado como no exemplo abaixo:

{
  "access_token": "6c164a82-84a6-3bc4-8122-f777121a4f62",
  "token_type": "access_token",
  "expires_in": 3600
}

Quando o publicador enviar um evento ao Events Hub, deve passar o access token recebido na requisição, seguindo a configuração do interceptor na política.

JWT Validation

O interceptor JWT Validation requer a validação de um token JWT que deve ser obtido pelo fluxo JWT de OAuth.

Ao incluir o interceptor na política desejada, é necessário incluir o nome sob o qual o valor do access token será passado (por exemplo: access_token) e o local em que ele será passado na requisição (header; default JWT header; ou query param).

Com uma app criada na Sensedia API Platform e com acesso à API Events Hub Authorization, utilizaremos as credenciais dessa app para a obtenção de um token JWT, que deverá depois ser passado pelo publicador quando enviar eventos ao Events Hub.

Para obtenção do token, devemos fazer duas requisições à API OAuth implantada na Plataforma do cliente.

A primeira requisição é para recebimento de um code, que é um requisito para a geração do token. Ela deve ser uma requisição POST para <url-do-gateway>/oauth/grant-code.

O header deve conter a seguinte informação:

Content-Type : application/json

No corpo, devemos enviar os seguintes itens:

{
  "client_id": "f9212173-e705-373b-a698-61923e378359",
  "extraInfo": {},
  "redirect_uri": "string",
  "state": "string"
}
O client ID a ser passado deve ser o mesmo da app registrada na Plataforma.

Feito isso, espera-se uma resposta contendo o code, como no exemplo abaixo.

{
  "redirect_uri": "string?state=string&code=8748d39f-1d4f-311f-92c6-4b279db1b317"
}

A segunda requisição deve passar o code retornado para que o token JWT seja gerado. Ela deve ser uma requisição POST para o endpoint <url-do-gateway>/oauth/access-token.

O header deve conter as seguintes informações:

Authorization : Basic client_id:client_secret

Esse client_id:client_secret deve ser uma string convertida em Base64, usando os dados da app registrada na Plataforma.

Exemplo de header com o client_id e o client_secret convertidos para Base64:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

No corpo, devemos passar o code gerado pelo endpoint de grant-code com mais alguns itens, no formato x-www-form-urlencoded:

"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer"
"code" : "8748d39f-1d4f-311f-92c6-4b279db1b317"

Por fim, o token será gerado e deverá ser retornado como no exemplo abaixo.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJsb2NhbGhvc3QiLCJpc3MiOiIxNzIuMTguMC4xIiwic3ViIjoiOWI1Zjc3MWUtNzgyZC0zNTEwLWI2YmEtMzZlOWM2NWJmZDVkIiwiZXhwIjozNjAwLCJpYXQiOjE1Mjg5MTg2MzcsIkFwcDogIjoiRGVtb0FwcCIsIkNvZGU6ICI6IjRlNWIyMTEzLTJkYzYtM2RlNi1iN2ZkLWNkOTYxOTMxZWQyOSIsImxvZ2luIjoidXNlci5sb2dpbiJ9.DVSd_yIKiWqIRpcFUhpB5JT9HMUE4mI5fAcpzs4QOkM",
  "token_type": "access_token",
  "expires_in": 3600
  }

Quando o publicador enviar um evento ao Events Hub, deve passar o token recebido na requisição, seguindo a configuração do interceptor na política.

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