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

O provedor de segurança de Chave de API permite que administradores protejam 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 um provedor de segurança de chave de API

Para adicionar um novo provedor de segurança de chave de API, siga estas etapas:

1. Vá para IDE > Provedores de Segurança. A página Segurança é aberta.

2. Na tabela Autenticação de Usuário, clique em + Autenticação de Usuário. O diálogo Provedor aparece:

   

3. Na seção Configurações, preencha estes campos:

   1. Nome: Insira um nome para identificar seu provedor de segurança de 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 o novo provedor de segurança.

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

4. Na seção Chaves, preencha estes campos:

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

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

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

5. Clique em Salvar.

Após salvar um novo provedor de segurança de chave de API, você será levado de volta à página Segurança, onde a tabela Autenticação de Usuário mostrará o novo que você acabou de criar. Ao clicar no ícone no final de sua linha, você pode continuar configurando-o.

Configurar um provedor de segurança de chave de API

Para configurar seu provedor de segurança de chave de API, vá para IDE > Provedores de Segurança. Localize-o 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 foram exibidas quando você criou o provedor de segurança. 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 por meio de 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 por meio de 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.

Gerar uma chave da API

Quando você tiver um provedor de segurança de chave da API configurado, pode gerar chaves da API associadas a usuários seguindo estas etapas:

1. Vá para IDE > Runtime > Gerenciamento de Usuários.

2. O painel Usuários lista todos os usuários. Localize o usuário para o qual deseja gerar uma chave da API e clique no ícone no final da sua linha.

3. No diálogo Usuário, clique em Mais > Chaves. O diálogo Chaves será aberto.

4. Clique em Criar. O diálogo Gerar Chave será aberto.

5. No menu Provedor, selecione o provedor de segurança de chave da API que você criou.

6. (Opcional) Forneça uma Descrição para esta chave e insira um tempo de expiração personalizado no campo Expira Em.

7. Clique em Salvar. A chave da API será criada.

Passar uma chave da API

Na maioria dos cenários, a Jitterbit recomenda que o cliente passe a chave da API por meio de 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

Esse é o comportamento padrão, que o App Builder seleciona automaticamente. Você também pode usar o parâmetro HttpHeaderName ao configurar sua chave de API para alterar o nome do cabeçalho HTTP que irá passar a chave de API do padrão X-API-Key.

Os seguintes exemplos são algumas exceções a essa recomendação:

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

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

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

   Nota

   No exemplo acima, a chave foi enviada sob o nome apiKey. Você pode alterar isso acessando a configuração da chave de API e adicionando o parâmetro QueryStringParameterName para escolher um nome diferente.