Tutorial: Usando a Sensedia API Platform para Autorização de Publicadores

O Events Hub permite que você use um servidor externo para validar client ID e/ou tokens de acesso dos publicadores que enviam requisições ao Events Hub. Uma das opções é utilizar a Sensedia API Platform para fazer essa validação.

Clientes do Sensedia API Management v5: Para validar client ID e/ou tokens de acesso dos publicadores, você deverá importar a API de autorização do Events Hub.

Imagine que você está organizando um evento em um local. Você quer que apenas pessoas autorizadas entrem. Então, você coloca um segurança na entrada para verificar a identidade das pessoas. O servidor de autorização atua da mesma forma. Você seleciona o tipo de validação que quer fazer e ele se certifica que seja cumprida.

Como funciona?

Na página de Policies, você pode criar políticas de segurança para aplicar aos handlers.

A configuração de URLs de autorização é feita por contexto. Ele é um dos marcadores da URL de publicação de eventos, formada por: URL base + context + handler + topic.

Existem 5 interceptores disponíveis e 4 precisam do servidor de autorização de publicadores para funcionar. São eles:

  • Access Token Validation

  • Client ID Validation

  • OAuth Validation

  • JWT Validation

Ao selecionar qualquer um deles, você precisa configurar a URL de autorização na tela Authorizations.

Obter a URL de autorização usando a Sensedia API Platform

Para utilizar a Sensedia API Platform como servidor de validação das policies:

  1. Acesse API Design > API Catalog e busque por API Events Hub Authorization;

  2. Na API Events Hub Authorization, vá até a seção Environments;

  3. Escolha o ambiente que deseja configurar, clique sobre o ícone icon link e copie a URL.
    Você precisará complementá-lo com a informação do interceptor, portanto, cole-o em um arquivo;

  4. Vá até a seção Resources and Operations e copie o path POST do tipo de interceptor que utilizará;

  5. Cole o path do interceptor no final da URL do ambiente. Esta será a URL do seu authorization;

  6. Com a URL completa copiada, acesse Events Hub > Authorizations e encontre o contexto que será validado por este authorization;

  7. Clique no ícone icon add1, cole a URL do authorization e salve.

Para cadastrar um contexto de teste para o authorization, na seção Environments, copie o link do seu ambiente de teste.

A seção Resources and Operations está dividida entre OAuth e JWT. Atenção ao copiar o path da sua URL:

  • A URL do authorization deve ser gerada respeitando as policies inseridas no contexto;

  • Se inseriu interceptores de OAuth Validation, copie o path de Oauth.

  • Se inseriu interceptores de JWT Validation, copie o path de JWT.

Configurar Client ID Validation

O interceptor Client ID Validation requer uma validação simples de client ID.

Ao cadastrar este interceptor para uma política, você precisa definir o nome que será usado para passar o valor de Client ID (por exemplo, client_id) e onde será passado na requisição (cookie; header; header ou cookie; query param; ou any).

Para usar o interceptor Client ID Validation, siga os passos:

  • Na Sensedia API Platform

    1. Acesse a Consumers > APPS e clique em + Create APP;

    2. Na aba APIS AND PLANS, busque por Events Hub Authorization 1.0 e selecione-a no botão SELECT ALL PLANS;

    3. Clique em PUBLISH YOUR APP;

  • No Events Hub

    1. Cadastre o Publisher

      1. Com a APP salva, acesse a tela Publishers;

      2. Coloque o cursor sobre o botão + e clique em Import From API Platform;

      3. Encontre a APP que cadastrou e clique em SAVE;

      4. Clique em ADD ENABLED TOPICS e vincule o publicador ao tópico que deseja;

      5. Na mesma tela, clique no ícone icon view topics para habilitar o contexto que será validado pelo interceptor. Se não habilitar nenhum, a validação não funcionará.

    2. Acesse o Handler

      1. Na tela de Handler, encontre o que cadastrou para essa validação;

      2. Na aba Topics, copie a URL do contexto habilitado para o interceptor de Client ID;

  • No Postman

    1. No POST, cole a URL do seu contexto;

    2. Insira o parâmetro de client ID no header da requisição, com o nome igual ao que cadastrou para a política (ex: client_id) e clique em Send;

    3. Você pode ver se a requisição foi bem-sucedida clicando sobre o ícone icon event status do seu handler.

Configurar Access Token Validation

O interceptor Access Token Validation requer a validação de um access token. Ele deve ser obtido usando o fluxo OAuth escolhido pelo publicador.

Ao cadastrar este interceptor para uma política, você precisa definir o nome que será usado para passar o valor de access token (por exemplo, access_token) e onde será passado na requisição (cookie; header; header ou cookie; query param; ou any).

Para configurá-lo, siga os passos:

  • Na Sensedia API Platform

    1. Acesse a Consumers > APPS e clique em + Create APP;

    2. Na aba APIS AND PLANS, busque por Events Hub Authorization 1.0 e selecione-a no botão SELECT ALL PLANS;

    3. Clique em PUBLISH YOUR APP.

Se já tem uma APP com plano vinculado à API Events Hub Authorization 1.0, você não precisa fazer isso novamente.

  • No Postman

    1. Gerar o access token

Para obter o token, você deve fazer uma requisição à API OAuth implantada na sua Plataforma. Vamos ensinar como fazer usando o fluxo client-credentials:

Para entender os outros fluxos disponíveis, acesse a documentação OAuth 2.0: fluxos de obtenção de access token.

1. No POST, faça uma requisição para o endpoint <url-do-gateway>/oauth/access-token;
2. No header da requisição, você deve passar:

Authorization : Basic client_id:client_secret

Exemplo de header com o client_id e o client_secret em Base64:

Authorization : Basic ZjkyMTIxNzMtZTcwNS0zNzNiLWE2OTgtNjE5MjNlMzc4MzU5OjAyYWI1Mjg4LTkyZGItM2FiMy05OWZkLWZhYzRhZjg1N2Q4MQ==

3. No body da requisição, você deve passar o grant_type no formato x-www-form-urlencoded:

"grant_type": "client_credentials"

4. O access token será gerado e retornado no body da requisição, como no exemplo abaixo:

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

  • Para testar a política:

    1. Copie a URL do seu contexto e cole no POST;

    2. Insira o parâmetro de access token no header da requisição, com o nome igual ao que cadastrou para a política (ex: access_token);

    3. Cole a chave do seu access token no valor e clique em Send;

    4. Você pode ver se a requisição foi bem-sucedida clicando sobre o ícone icon event status do seu handler.

Configurar OAuth Validation

O interceptor OAuth Validation requer a validação de client ID e access token. Se ainda não configurou, veja os tópicos:

Os valores de client ID e access token devem ser passados no header da requisição.

  • Testando a política no Postman

    1. Copie a URL do seu contexto e cole no POST;

    2. Cole no header o valor do seu client ID;

    3. Cole no header o valor do seu access token;

    4. Clique em Send;

    5. Você pode ver se a requisição foi bem-sucedida clicando sobre o ícone icon event status do seu handler.

Configurar JWT Validation

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

Ao cadastrar este interceptor para uma política, você precisa definir o nome que será usado para passar o valor de access token (por exemplo, access_token) e onde será passado na requisição (header; default JWT header; ou query param).

Para que este interceptor funcione, você deve cadastrar a URL do authorization JWT do seu contexto na tela de Authorizations.
Veja como obter a URL de autorização usando a Sensedia API Platform.

Para configurá-lo, siga os passos:

  • Na Sensedia API Platform

    1. Acesse a Consumers > APPS e clique em + Create APP;

    2. Na aba APIS AND PLANS, busque por Events Hub Authorization 1.0 e selecione-a no botão SELECT ALL PLANS;

    3. Clique em PUBLISH YOUR APP.

Se já tem uma APP com plano vinculado à API Events Hub Authorization 1.0, você não precisa fazer isso novamente.

  • No Postman

1. Gerar o code

Para obter o token, você precisa gerar o code fazendo uma requisição à API OAuth implantada na sua Plataforma.

1. No POST, faça uma requisição para o endpoint <url-do-gateway>/oauth/grant-code;
2. No header da requisição, você deve passar:

Content-Type : application/json

3. No body, passe as informações abaixo. Lembre-se de substituir o client ID do exemplo pelo da sua APP:

{
  "client_id": "f9212173-e705-373b-a698-61923e378359",
  "extraInfo": {},
  "redirect_uri": "string",
  "state": "string"
}
A redirect_uri precisa ser preenchida com uma URL. Você pode inserir, por exemplo: "http://teste.com.br".

Na resposta, será retornado o code após o sinal de =, como no exemplo abaixo:

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

2. Gerar o token JWT

Com o code copiado, você pode gerar o token JWT:

1. No POST, faça uma requisição para o endpoint <url-do-gateway>/oauth/access-token;
2. No header da requisição, você deve passar:

Authorization : Basic client_id:client_secret

3. No body, selecione o formato json e passe as informações abaixo, com o número do code que gerou na requisição anterior:

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

4. O token será retornado na resposta da requisição, como no exemplo abaixo:

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

  • Testando a política no Postman

    1. Copie a URL do seu contexto e cole no POST;

    2. Cole no header o valor do seu token JWT;

    3. Clique em Send;

    4. Você pode ver se a requisição foi bem-sucedida clicando sobre o ícone icon event status do seu handler.

Thanks for your feedback!
EDIT

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