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

O provedor de segurança API Key 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 tanto autenticação quanto autorização.

Definição e casos de uso

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

DLOo9sPS5slJEMHpXBFt3g

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

• Elas têm maior entropia do que combinações de nome de usuário e senha.
• Elas podem sobreviver a uma redefinição de senha.
• Elas podem ser facilmente revogadas.
• Elas podem ser rotacionadas.
• Elas são mais rápidas. Senhas devem ser hashadas, o que é deliberadamente lento.

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

• Contas de nível de serviço
• Comunicação de aplicativo para aplicativo
• 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, vá para IDE > Provedores de Segurança.

A página Segurança será exibida, onde a tabela Autenticação de Usuário mostrará todos os métodos de autenticação de usuário atuais. Se não houver chaves de API ou se você quiser criar uma nova, clique no botão + Autenticação de Usuário. O diálogo Provedor aparecerá, 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. Fazer isso alterará os demais campos que são exibidos no 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. Ativado: 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 de novas chaves. (Alterar este campo não afeta chaves existentes.)

   2. Expiração Máxima: Insira quantos minutos para a vida útil máxima de novas chaves. (Alterar este campo não afeta chaves existentes.)

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

Quando terminar, clique em Salvar. Se quiser sair sem salvar, clique em Cancelar. Após salvar uma nova chave de API, você será levado de volta à página Segurança, onde a tabela Autenticação de Usuário mostrará a nova chave de API que você acabou de criar. Ao clicar no ícone no final de sua linha, você pode continuar configurando-a.

Configurar uma chave de API

Para configurar uma chave de API, vá para IDE > Provedores de Segurança. Localize a chave de API que deseja editar na tabela Autenticação de Usuário e clique no ícone no final de sua linha. A página Provedor será exibida, onde você pode 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á o 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 da API seja passada na string de consulta em vez de no cabeçalho HTTP (veja a seção Passar uma chave da API). O valor padrão é False.

• AllowInsecureHttp: Use este parâmetro para permitir que a chave da API seja passada via uma solicitação HTTP insegura em vez de uma solicitação HTTPS segura (veja a seção Passar uma chave da API). 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 tiver usado a opção AllowApiKeyInQueryString para passar a chave da API via um dos parâmetros da string de consulta, pode usar esta opção para alterar o nome do parâmetro do nome padrão apiKey (veja a seção Passar uma chave da API).

Clique em Salvar e feche o diálogo de Propriedades. O novo parâmetro que você adicionou será listado na tabela de Propriedades.

Passar uma chave da API

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

GET /Vinyl/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 você quiser ou precisar, pode usar o parâmetro HttpHeaderName ao configurar sua chave da API para alterar o nome do cabeçalho HTTP que passará a chave da API do padrão X-API-Key.

Os seguintes exemplos são algumas exceções a essa 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 da API enviadas via conexões HTTP definindo o parâmetro AllowInsecureHttp como True durante a configuração da chave da API.

2. Em casos onde você não tem acesso aos cabeçalhos da solicitação HTTP, também é possível enviar a chave da API via os parâmetros da string de consulta. Para habilitar esta opção, defina AllowApiKeyInQueryString como True nas configurações da chave da API. O exemplo abaixo ilustra como a chave da API é passada neste cenário:

GET /Vinyl/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 da API e adicionando o parâmetro QueryStringParameterName para escolher um nome diferente.