Ir para o conteúdo

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:

  1. Acesse IDE > Security Providers. A página Security abre.

  2. Clique em + Security Provider. A página Provider aparece:

    Provider page

  3. Na seção Settings, preencha estes campos:

    1. Name: Insira um nome para identificar seu provedor de segurança de chave de API.

    2. 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.

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

    4. Enabled: Clique nesta caixa de seleção para ativar o novo provedor de segurança.

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

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

    1. Default Expiry: Insira quantos minutos para o tempo de vida padrão das novas chaves. (Alterar este campo não afeta as chaves existentes.)

    2. Max Expiry: Insira quantos minutos para o tempo de vida máximo das novas chaves. (Alterar este campo não afeta as chaves existentes.)

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

  5. 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:

properties dialog

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ão X-API-Key.

  • QueryStringParameterName: Quando você também tiver usado a opção AllowApiKeyInQueryString para 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ão apiKey (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:

  1. Acesse IDE > Runtime > User Management.

  2. 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.

  3. Na caixa de diálogo User, clique em More > Keys. A caixa de diálogo Keys é aberta.

  4. Clique em Create. A caixa de diálogo Generate Key será aberta.

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

  6. (Opcional) Forneça uma Description para esta chave e insira um tempo de expiração personalizado no campo Expires In.

  7. 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:

  1. 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 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 por meio dos parâmetros de string de consulta. Para ativar esta opção, defina AllowApiKeyInQueryString como True nas 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/json
    

    Nota

    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âmetro QueryStringParameterName para escolher um nome diferente.