Provedor de segurança de chave de API no Jitterbit App Builder

O provedor de segurança Chave de API permite que os administradores protejam as APIs REST do App Builder usando um código de chave de API gerado pelo App Builder. O consumidor passa a chave de API para o App Builder ao fazer solicitações de API REST. Como cada chave de API está associada a um usuário individual, isso fornece autenticação e autorização.

Definição e casos de uso

As chaves de API do App Builder consistem em um número criptograficamente aleatório de 128 bits. As chaves são codificadas em base64url. Veja abaixo um exemplo de uma chave de API:

DLOo9sPS5slJEMHpXBFt3g

As chaves de API têm as seguintes vantagens em relação à autenticação padrão de nome de usuário/senha:

• Elas têm maior entropia do que combinações de nome de usuário e senha.
• Eles podem sobreviver a uma redefinição de senha.
• Elas podem ser facilmente revogadas.
• Eles podem ser girados.
• Eles são mais rápidos. As senhas precisam ser criptografadas, o que é deliberadamente lento.

As desvantagens, ou fraquezas, das chaves de API incluem o gerenciamento de sua distribuição e o risco de vazamentos. Alguns dos casos de uso em que as chaves de API podem ser o método de autenticação mais adequado incluem:

• Contas de nível de serviço
• Comunicação entre aplicações
• Comunicação de servidor para servidor
• Acesso somente leitura
• Informações não sensíveis

Adicionar uma chave de API

Para adicionar uma nova chave de API, acesse IDE > Provedores de segurança.

A página Segurança será exibida, onde a tabela Autenticação do Usuário exibirá todos os métodos de autenticação de usuário atuais. Se não houver nenhuma chave de API ou se você quiser criar uma nova, clique no botão + Autenticação do Usuário. A caixa de diálogo Provedor será exibida, contendo os seguintes campos:

1. Na seção Configurações:

   1. Nome: Insira um nome para identificar sua chave de API.

   2. Tipo: No menu suspenso, selecione Chave de API como o tipo de provedor de segurança que você está criando. Isso alterará os demais campos exibidos na caixa de diálogo.

   3. Prioridade: Insira um número para definir a ordem em que os provedores de segurança aparecem no formulário de login.

   4. Habilitado: Clique nesta caixa de seleção para ativar sua chave de API.

   5. Identificador: Este campo é gerado automaticamente pelo App Builder.

2. Na seção Chaves:

   1. Expiração Padrão: Insira quantos minutos para a vida útil padrão das novas chaves. (Alterar este campo não afeta as chaves existentes.)

   2. Validade Máxima: Informe quantos minutos são necessários para a vida útil máxima das novas chaves. (Alterar este campo não afeta as chaves existentes.)

   3. Comprimento: Insira o comprimento (em bytes) das novas chaves. (Alterar este campo não afeta as chaves existentes.)

Ao terminar, clique em Salvar. Se desejar sair sem salvar, clique em Cancelar. Após salvar uma nova chave de API, você retornará à página Segurança, onde a tabela Autenticação do Usuário exibirá a nova chave de API que você acabou de criar. Ao clicar em no final da linha, você pode continuar configurando-o.

Configurar uma chave de API

Para configurar uma chave de API, acesse IDE > Provedores de Segurança. Localize a chave de API que deseja editar na tabela Autenticação do Usuário e clique no botão no final da linha. A página Provedor será exibida, onde você poderá adicionar configurações adicionais. O painel Provedor à esquerda mostra as mesmas configurações e chaves que são exibidas ao criar uma nova chave. O painel Propriedades à direita permite que você configure alguns parâmetros extras, descritos abaixo.

Para adicionar uma nova propriedade, clique no botão + Propriedade. Isso abrirá a caixa de diálogo Propriedades, que contém os campos Parâmetro e Valor. Os seguintes parâmetros estão disponíveis:

• AllowApiKeyInQueryString: Use este parâmetro para permitir que a chave de API seja passada na string de consultar em vez de no cabeçalho HTTP (consulte Passar uma chave de API seção). O valor padrão é False.

• AllowInsecureHttp: Use este parâmetro para permitir que a chave de API seja passada por meio de uma solicitação HTTP insegura em vez de uma solicitação HTTPS segura (consulte Passar uma chave de API seção). O valor padrão é False.

• HttpHeaderName: Use este parâmetro para alterar o nome do cabeçalho HTTP que passará a chave da API do padrão X-API-Key.

• QueryStringParameterName: Quando você também usou o AllowApiKeyInQueryString opção para passar a chave da API por meio de um dos parâmetros da string de consultar, você pode usar esta opção para alterar o nome do parâmetro do nome padrão apiKey (veja Passar uma chave de API seção).

Clique em Salvar e feche a caixa de diálogo Propriedades. O novo parâmetro adicionado será listado na tabela Propriedades.

Passe uma chave de API

Na maioria dos cenários, a Jitterbit recomenda que o cliente passe a chave de API por meio de um cabeçalho personalizado em uma conexão HTTPS segura para limitar o risco de exposição. O exemplo a seguir ilustra isso:

GET /App Builder/rest/v1/sales/customers HTTP/1.1
Host: example.com:443
Accept: application/json
X-API-Key: ABCd0eFG1hiJKLMnOPQr2s

Este é o comportamento padrão, que o App Builder adota automaticamente. Se desejar ou precisar, você pode usar o HttpHeaderName parâmetro ao configurar sua chave de API para alterar o nome do cabeçalho HTTP que passará a chave da API do padrão X-API-Key.

Os exemplos a seguir são algumas exceções a esta recomendação:

1. Em alguns cenários, as conexões HTTPS podem ser encerradas prematuramente. Para contornar esse problema, você pode forçar o App Builder a aceitar chaves de API enviadas por meio de conexões HTTP, definindo a propriedade AllowInsecureHttp parâmetro para True durante configuração da chave API.

2. Nos casos em que você não tem acesso aos cabeçalhos de requisição HTTP, também é possível enviar a chave de API por meio dos parâmetros da string de consultar. Para habilitar esta opção, defina a opção AllowApiKeyInQueryString para True nas configurações de chave de API. O exemplo abaixo ilustra como a chave de API é passada neste cenário:

   GET /App Builder/rest/v1/sales/customers?apiKey=ABCd0eFG1hiJKLMnOPQr2s HTTP/1.1
   HOST: example.com:443
   Accept: application/json
   

   Observe que no exemplo acima a chave foi enviada com o nome apiKey. Você pode alterar isso acessando a Configuração da chave de API e adicionando o QueryStringParameterName parâmetro para escolher um nome diferente.