Provedor de segurança de chave de API no Jitterbit App Builder
O provedor de segurança API Key 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 ao App Builder ao fazer requisiçõ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 criptograficamente aleatório de 128 bits. As chaves são codificadas em base64url. Abaixo está um exemplo de 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:
- Possuem maior entropia do que combinações de nome de usuário e senha.
- Podem sobreviver a uma redefinição de senha.
- Podem ser facilmente revogadas.
- Podem ser rotacionadas.
- São mais rápidas. Senhas precisam ser criptografadas, o que é deliberadamente lento.
As desvantagens ou fraquezas das chaves de API incluem gerenciar 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 no nível de serviço
- Comunicação aplicação-para-aplicação
- Comunicação 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:
-
Acesse IDE > Security Providers. A página Security abre.
-
Clique em + Security Provider. A página Provider aparece:

-
Na seção Settings, preencha estes campos:
-
Name: Insira um nome para identificar seu provedor de segurança de chave de API.
-
Type: No menu suspenso, selecione API Key como o tipo de provedor de segurança que você está criando. Isso alterará os demais campos mostrados no diálogo.
-
Priority: Insira um número para definir a ordem em que os provedores de segurança aparecem no formulário de login.
-
Enabled: Clique nesta caixa de seleção para ativar o novo provedor de segurança.
-
Identifier: Este campo é gerado automaticamente pelo App Builder.
-
-
Na seção Keys, preencha estes campos:
-
Default Expiry: Insira quantos minutos para o tempo de vida padrão das novas chaves. (Alterar este campo não afeta as chaves existentes.)
-
Max Expiry: Insira quantos minutos para o tempo de vida máximo das novas chaves. (Alterar este campo não afeta as chaves existentes.)
-
Length: Insira o comprimento (em bytes) das novas chaves. (Alterar este campo não afeta as chaves existentes.)
-
-
Clique em Save.
Após salvar um novo provedor de segurança de chave de API, você retornará à página Security, onde o painel Security Providers mostrará o novo que você criou. Clicando no ícone ao 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, acesse IDE > Security Providers. Localize-o no painel Security Providers e clique no ícone ao final de sua linha. A página Provider será exibida, onde é possível adicionar configurações extras. O painel Provider à esquerda mostra as mesmas configurações e chaves exibidas quando você criou o provedor de segurança. O painel Properties à direita permite configurar alguns parâmetros extras, descritos abaixo.
Para adicionar uma nova propriedade, clique no botão + Property. Isso abrirá o diálogo Properties, que contém os campos Parameter e Value. Os seguintes parâmetros estão disponíveis:

Nota
Nenhum desses parâmetros é obrigatório. Você deve adicioná-los apenas se houver necessidade de alterar a forma como sua chave de API será passada a partir da configuração padrão. Consulte Passar uma chave de API para saber mais.
-
AllowApiKeyInQueryString: Use este parâmetro para permitir que a chave de API seja passada na string de consulta em vez do cabeçalho HTTP (consulte a seção Passar uma chave de API). O valor padrão éFalse. -
AllowInsecureHttp: Use este parâmetro para permitir que a chave de API seja passada via uma solicitação HTTP insegura em vez de uma solicitação HTTPS segura (consulte a seção Passar uma chave de API). O valor padrão éFalse. -
HttpHeaderName: Use este parâmetro para alterar o nome do cabeçalho HTTP que passará a chave de API do padrãoX-API-Key. -
QueryStringParameterName: Quando você também tiver usado a opçãoAllowApiKeyInQueryStringpara passar a chave de API por um dos parâmetros de string de consulta, é possível usar esta opção para alterar o nome do parâmetro do nome padrãoapiKey(consulte a seção Passar uma chave de API).
Clique em Save e feche a caixa de diálogo Properties. O novo parâmetro que você adicionou será listado na tabela Properties.
Gerar uma chave de API
Quando você tem um provedor de segurança de chave de API configurado, é possível gerar chaves de API associadas aos usuários seguindo estas etapas:
-
Acesse IDE > Runtime > User Management.
-
O painel Users lista todos os usuários. Localize o usuário para o qual deseja gerar uma chave de API e clique no ícone no final de sua linha.
-
Na caixa de diálogo User, clique em More > Keys. A caixa de diálogo Keys é aberta.
-
Clique em Create. A caixa de diálogo Generate Key será aberta.
-
No menu Provider, selecione o provedor de segurança de chave de API que você criou.
-
(Opcional) Forneça uma Description para esta chave e insira um tempo de expiração personalizado no campo Expires In.
-
Clique em Save. A chave de API será criada.
Passar uma chave de API
Na maioria dos cenários, a Jitterbit recomenda que o cliente passe a chave de API por um cabeçalho personalizado em uma conexão HTTPS segura para limitar o risco de exposição. O exemplo a seguir 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 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 passará a chave de API do padrão X-API-Key.
Os exemplos a seguir são algumas exceções a esta recomendação:
-
Em alguns cenários, as conexões HTTPS podem ser encerradas prematuramente. Para contornar este problema, você pode forçar o App Builder a aceitar chaves de API enviadas via conexões HTTP definindo o parâmetro
AllowInsecureHttpcomoTruedurante a configuração da chave de API. -
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 por meio dos parâmetros de string de consulta. Para ativar esta opção, defina
AllowApiKeyInQueryStringcomoTruenas configurações de chave de API. O exemplo abaixo ilustra como a chave de API é passada neste cenário:GET /Vinyl/rest/v1/sales/customers?apiKey=ABCd0eFG1hiJKLMnOPQr2s HTTP/1.1 HOST: example.com:443 Accept: application/jsonNota
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 parâmetroQueryStringParameterNamepara escolher um nome diferente.