Essa funcionalidade permite armazenar tokens de autenticação para APIs e protocolos OAuth 2.0. Com isso, as chaves ficam centralizadas em um único local e podem ser obtidas automaticamente ao requisitar o recurso dentro da aplicação, proporcionando maior praticidade e segurança no gerenciamento de autenticação.

Ao adotar o uso de API Keys, o Cronapp permite aos desenvolvedores criar e gerenciar chaves exclusivas de acesso, promovendo uma autenticação simplificada e direta. Essas chaves, quando devidamente configuradas, tornam-se um meio seguro e eficaz para autorizar solicitações à API, garantindo o fluxo controlado de dados entre a aplicação e os serviços associados.

A integração do protocolo OAuth 2.0 acrescenta uma camada adicional de segurança e versatilidade ao sistema de gerenciamento de tokens do Cronapp. Ao possibilitar a autenticação de usuários por meio de provedores de identidade confiáveis, o OAuth 2.0 confere um processo robusto de autorização, permitindo que as aplicações utilizem tokens de acesso para interagir com recursos protegidos.

Acessando a funcionalidade

Acesse a partir do menu do sistema Projeto > Gerenciamento de Tokens, conforme a figura abaixo.


Figura 1 - Acessando a funcionalidade Gerenciamento de Tokens


Os campos da área Configuração (destaque 4 da figura 1) são adaptados conforme opção selecionada no campo Tipo (2):

  1. Nome: caixa de seleção com os tokens criados. Inicialmente só existe o token "Padrão".
    1. Adicionar: adiciona um novo token. Ao clicar neste botão, um pop-up será exibido, solicitando a inserção de um nome para o novo token. Não é possível haver mais de um token com o mesmo nome.
    2. Editar: altera o rótulo do token selecionado. Ao clicar neste botão, um pop-up será exibido, solicitando a inserção de um novo valor para o token. 
    3. Remover: remove o token selecionado.
  2. Tipo: indica o tipo de autenticação que está sendo configurado, "API" Key ou "OAuth 2".
  3. Urls dos Servidores de Recursos: especifica as URLs dos servidores de recursos associados à API ou OAuth 2.0. 
    1. Adicionar: ao clicar neste botão, a parte interna do campo Url ficará habilitada, permitindo inserir o endereço da API ou do OAuth 2.0, conforme o "Tipo" selecionado.
    2. Remover: remove uma URL selecionada.
  4. Configuração: dependendo da escolha no parâmetro "Tipo", a seção "Configuração" será modificada, exibindo os campos necessários para a configuração da API Key ou do OAuth 2.0. Confira a seguir.
    • OAuth 2.0:
      • Tipo de Concessão: refere-se ao fluxo específico usado para obter tokens de acesso. O Cronapp utiliza somente o "Client Credentials".
      • Método de Autenticação: o OAuth 2.0 define vários métodos de autenticação para diferentes cenários de uso. Entre eles, destacam-se os métodos de autenticação "Basic", "None" e "POST".
        • Basic: as credenciais são codificadas em Base64 e incluídas no cabeçalho da requisição HTTP.
        • None: não é fornecida nenhuma informação de autenticação. Este método é geralmente usado quando o cliente não precisa de autenticação explícita.
        • Post: as credenciais do cliente são enviadas no corpo de uma requisição POST. Esse método é comumente usado para solicitar um token de acesso ao servidor de autorização quando as credenciais são enviadas diretamente ao servidor.
      • Client Id: é um identificador exclusivo atribuído ao cliente pela entidade que emite os tokens (como o servidor de autorização OAuth 2.0).
      • Client Secret: é uma chave secreta conhecida apenas pelo cliente e pela entidade que emite os tokens.
      • Token URI: Uniform Resource Identifier específica do Token Endpoint, local para o qual o servidor de autorização direcionará o usuário quando o aplicativo for autorizado e receber um token de acesso.
    •  Api Key: 
      • Parâmetro da Api Key: representa o cabeçalho da requisição, usado para enviar a chave de API nas solicitações.
      • Local da Api Key: indica o local em que a chave de API deve ser incluída na requisição HTTP. No momento, o Cronapp só disponibiliza a opção de incluir a chave no cabeçalho (Header).
      • Valor da Api Key: neste campo será inserido o valor real da chave de API associada ao cliente ou aplicativo. A chave de API é usada para autenticar e autorizar o acesso à API.


Sempre que fizer uma alteração na janela de Gerenciamento de Tokens, será necessário parar e rodar o projeto novamente, caso contrário, as alterações não serão aplicadas.

Exemplos

Dividimos os exemplos desta documentação em duas partes. Inicialmente exibiremos o método de utilização da Api Key, apresentando o status de uma requisição realizada através do bloco Obter conteúdo da URL quando o campo "Valor da Api Key" , da janela Gerenciamento de Tokens, estiver preenchido e quando estiver vazio, respectivamente. 

Para o exemplo de utilização do tipo de token OAuth 2.0, criamos uma API em node.js onde exibiremos uma lista contendo id's e nomes de usuários. Protegemos essa API utilizando um sistema baseado em nuvem chamado Okta.

API Key

Exemplo 1

Para ilustrar o emprego de tokens do tipo Api Key, consideraremos a API The Cat Api. Ela possibilita que os usuários realizem solicitações HTTP para obter imagens aleatórias de gatos, informações sobre raças específicas ou outros dados relacionados. Alguns dados dessa API podem ser obtidos sem a necessidade de adicionar uma chave de API, entretanto, para acessar determinadas informações, é necessário utilizar uma chave.

Nas seção Urls dos Servidores de Recursos, adicionamos o endpoint (destaque 1 da figura 2) que será utilizado para a requisição. Ao criar uma conta no site, um e-mail será enviado contendo o campo correspondente ao "Parâmetro da Api Key" (2) e o "Valor da API Key" (4). O destaque 3, referente ao "Local da Api Key", será sempre Header.


Figura 2 - Criando um token para Api Key


Para demonstrar o uso do token cadastrado, utilizaremos o bloco de programação Obter conteúdo da URL sem passar o parâmetro "Cabeçalho da requisição", campo necessário para acessar uma API com campos que necessitam de autenticação. Exibiremos apenas o status da conexão, baseado nos dados preenchidos na figura 2. Criamos um botão em uma view e associamos a função criada ao evento "Ao Clicar".


Figura 2.1 - Status da conexão obtido a partir da configuração da figura 2


Observe que a resposta obtida foi código 200, isso sinaliza que o acesso à API foi bem sucedido, mesmo não passando os dados de cabeçalho da requisição. Isso só foi possível graças a funcionalidade de gerenciamento de token. Dessa forma, os dados de acesso a esse endpoint estão salvos de forma global no Cronapp, e não há mais a necessidade de inseri-los novamente em requisições futuras.

Exemplo 2

Agora faremos uma requisição ao mesmo endpoint inserido na figura 2, porém, iremos retirar a chave de acesso do parâmetro Valor da API Key.


Figura 2 - Criando um token para Api Key sem a chave


Agora a resposta obtida foi um código 401, AUTHENTICATION_ERROR, ou seja, para acessar a API novamente, o usuário terá que preencher o parâmetro Cabeçalho da requisição do bloco Obter conteúdo da URL. com a chave de acesso e o valor da mesma.


Figura 2.1 - Status da conexão obtido a partir da configuração da figura 2

OAuth 2.0

Exemplo 

Para exemplificar a utilização do OAuth 2.0, criamos uma API baseada no tutorial Secure a Node API with OAuth 2.0 Client Credentials e um arquivo JSON de testes com lista de id's e nomes de usuários, que tentaremos acessar através do Cronapp. Para proteger esta aplicação, utilizamos o Okta, um serviço baseado em nuvem que permite aos desenvolvedores armazenar tokens OAuth 2.0, contas e dados de usuário de maneira fácil e segura e, em seguida, conectá-los a um ou vários aplicativos. Publicamos a API utilizando o Vercel, uma plataforma de hospedagem e automação para desenvolvimento web.

Após configurar sua conta no Okta, já é possível preencher os campos da janela "Gerenciamento de Tokens" para OAuth 2.0. Inserimos a URL de acesso ao arquivo JSON, que contém o nome e id's dos usuários, no campo "URL" (destaque 1 da figura 3). O restante dos campos é fornecido pela entidade que emite os tokens, neste caso, o Okta.


Figura 3 - Configuração do OAuth 2.0


Para acessar os dados dessa API através do Cronapp, utilizaremos uma Fonte de dados do tipo Web Service. Acesse a aba "Arquivos" e, em seguida, crie uma nova Fonte de dados, clicando no ícone (+) ao lado da Fonte de Dados (destaque 1 da figura 3.1). Demos o nome "PesquisarUsuario" tanto para o Identificador (2) quanto para o Nome da consulta (3), selecionamos o tipo "Web Services" (4) e inserimos a rota de acesso ao arquivo JSON da API, o mesmo que usamos nas configurações do Gerenciador de tokens. Essa API apresenta apenas dois campos (6), "name" e "id", os quais precisamos especificar no "Campo a adicionar" (7). Por fim, clique em salvar as alterações (8).


Figura 3 - Configuração do OAuth 2.0


Clique com o botão direito sobre a Fonte de dados criada (destaque 1 da figura 3.1) e escolha a opção "Criar visão para a entidade", através do menu "Ação" (2). Em seguida, escolha o tipo de modelo "Formulário de Pesquisa Web" (3), altere o nome do arquivo (4) e avance até finalizar a criação do formulário (5).


Figura 3.1 - Criação da view a partir da Fonte de dados


Acessando a view criada anteriormente, é possível ver os dados que foram obtidos da API exibidos na Grade.


Figura 3.2 - Dados da API exibidos na grade

Nesta página