Instalar um gateway de API privado Jitterbit no Linux

Visão geral

Esta página explica como instalar, configurar e testar um gateway de API privado.

Requisitos do sistema

Esta seção fornece os requisitos mínimos para um host de gateway de API.

Hardware

Sistemas operacionais

Rede

• Um subdomínio ou nome de domínio, apontado para o servidor (por exemplo, mysubdomain.example.com).

• Um certificado SSL válido para o subdomínio, de uma autoridade certificadora reconhecida; não utilize um certificado autoassinado.

  O certificado deve consistir em dois arquivos: um arquivo CRT (.crt) para o certificado assinado e KEY (.key) para a chave privada. Estes devem estar no formato PEM que um servidor NGINX pode entender. (Às vezes, a extensão dos arquivos é diferente; frequentemente, as extensões CRT, PEM e CER são intercambiáveis.) Também é possível que os dois arquivos estejam combinados em um único arquivo PFX. Nesse caso, utilize o OpenSSL para extrair os dois arquivos.

  Dica

  Certificados SSL gratuitos estão disponíveis de provedores como Let's Encrypt.

• Conectividade SSH.

Contas

Sua Harmony deve ter um papel com permissão Admin. (Apenas a permissão Agent Install não é suficiente.)

Recomendações

Ao configurar o host do seu gateway de API, você deve seguir os pontos recomendados:

• Não compartilhe o host com outros aplicativos não relacionados ao sistema.

• Configure o host para desempenho ideal.

• Instale os seguintes pacotes adicionais para o seu tipo de host:

  • Red Hat Enterprise Linux (RHEL): Se for baseado em nuvem, use um nó de Computação, com os seguintes grupos de pacotes:

    • Ferramentas de Depuração.
    • Utilitários de Monitoramento de Hardware.
    • Bibliotecas de Compatibilidade.
    • Ferramentas de Desenvolvimento.
    • Ferramentas de Segurança.

  • Debian, Ubuntu: Use uma instalação padrão e selecione os seguintes pacotes adicionais:

    • OpenSSH.

• Rede: Abra a porta 443 (HTTPS). Você pode usar os seguintes comandos para fazer isso:

  Red Hat, Amazon LinuxDebian, Ubuntu

  firewall-cmd --zone=public --add-port=443/tcp --permanent
  firewall-cmd --reload
  

  ufw allow 443/tcp
  

Instalar e configurar um gateway de API privado

Para instalar e configurar um gateway de API privado, siga estas etapas usando uma conta com privilégios de root:

1. Baixe um dos seguintes pacotes de software do gateway de API privado na página Downloads do Portal Harmony e, em seguida, copie-o para o seu host do gateway de API:

   • Linux RPM: O arquivo de pacote .rpm, para instalação no Red Hat ou Amazon Linux.

   • Linux Debian: O arquivo de pacote .deb, para instalação no Debian ou Ubuntu Linux.

2. Execute estes comandos para sua combinação de sistema operacional e versão do gateway, substituindo x.x.x.x (.deb) ou x.x.x-x (.rpm) pelo número da versão baixada:

   Red Hat, Amazon LinuxDebian, UbuntuUbuntu 24.04 LTS

   Gateway de API 10.61 ou anteriorGateway de API 10.62 ou posterior

   yum update
   yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
   

   yum update
   yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
   yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
   

   Gateway de API 10.61 ou anteriorGateway de API 10.62 ou posterior

   apt-get update
   apt-get install libzzip-dev libyaml-dev
   apt --fix-broken install
   apt install python
   dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb
   

   apt-get update
   apt-get -y install libgeoip-dev
   apt --fix-broken install
   ln -s /usr/bin/python2.7 /usr/bin/python
   dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb
   

   Gateway de API 11.38 ou posterior

   apt-get update
   apt-get install libzzip-dev libyaml-dev libpcre3
   apt --fix-broken install
   dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb
   

3. Desde a versão 11.49, o processo de instalação adiciona o seguinte arquivo de configuração logrotate para os logs do NGINX:

   /etc/logrotate.d/nginx
   

   (Opcional) Abra este arquivo, revise as configurações e ajuste onde necessário.

4. Copie e renomeie seus arquivos de certificado usando os seguintes comandos:

cp ca.crt /usr/local/openresty/nginx/ssl/nginx.crt
cp ca.key /usr/local/openresty/nginx/ssl/nginx.key

1. Adicione os arquivos de certificado ao Java KeyStore do Jitterbit.

2. Execute o seguinte comando e responda às perguntas:

   jitterbit-api-gateway-config
   

   Dica

   Para ajuda sobre o comando jitterbit-api-gateway-config, execute-o com a opção --help.

   Notas importantes

   • As informações que você fornecer são armazenadas no arquivo /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml. Neste arquivo, seu nome de usuário e senha do Harmony são criptografados, mas o nome de usuário e a senha do servidor proxy são codificados em base64 apenas. Você deve garantir que este arquivo tenha as permissões apropriadas para evitar que outros usuários leiam esses valores.

   • Na primeira vez que você configurar um gateway de API privado usando credenciais do Harmony, um novo usuário de gateway de API separado com uma senha que não expira é criado automaticamente na organização com um papel de Administrador. Este usuário não está associado a um endereço de email, não pode fazer login no portal do Harmony e é apenas para o gateway de API. As credenciais para este usuário são adicionadas ao arquivo gatewayconfig.yaml.

   • Desde a versão 11.32 do gateway de API, se você reconfigurar o gateway, será feita a seguinte pergunta adicional:

     Você gostaria de gerar novas credenciais de Gateway e sobrescrever as existentes? (y/N):
     

     Se você responder N, as credenciais do usuário existente são usadas. Se você responder Y, um novo usuário é criado.

   • Os usuários do gateway de API são exibidos na página Gerenciamento de Usuários do Console de Gerenciamento na forma <GatewayUser>_<orgID>_<ID>. Se o mesmo usuário reconfigurar o gateway na mesma organização, o nome do usuário do gateway é acrescido de um sublinhado e um número incrementado, como _1.

   Saída de exemplo

   Jitterbit Private Gateway Configuration
   
   Enter your Harmony user name:
   Enter your Harmony password:
   Are you an NA, EMEA or APAC customer (Enter one, NA , EMEA, or APAC):
   
   Would you like to enable a proxy (Y/N)?
   Enter your proxy server uri (e.g. http://192.168.1.100:808):
   Enter your proxy username:
   Enter your proxy password:
   
   Connecting to Harmony...
   NOTE: Default Jitterbit Services URL for NA customers is https://services.jitterbit.net/apis
   NOTE: Default Jitterbit Services URL for EMEA customers is https://services.jitterbit.eu/apis
   NOTE: Default Jitterbit Services URL for APAC customers is https://services.jitterbit.cc/apis
   
   Enter Jitterbit Services URL (press enter for default):
   Enter your Jitterbit Organization ID (press enter for default):
   Creating Private Gateway User...
   
   Here is the content of the DNS file that will be used for the API gateway:
   The file is located here: /usr/local/openresty/nginx/conf/dnsservers.conf
   resolver 127.0.1.1 valid=300s ipv6=off;
   
   Here are the nameservers from /etc/resolve.conf:
   nameserver 127.0.1.1
   
   Would you like to use the resolv.conf DNS nameservers rather than the default nginx DNS servers? (Y/N)?
   
   Would you like to manually add the DNS server the API gateway DNS configuration (Y/N)?
   Please enter IP address or domain name. Press enter to finish:
   
   Gateway Configuration file modified.
   
   If you have an SSL Certificate, copy the SSL Certificate file to
       /usr/local/openresty/nginx/ssl/nginx.crt
   and the SSL Certificate key file to
       /usr/local/openresty/nginx/ssl/nginx.key
   
   Would you like the Gateway Server started? (Y/N)?
   . . .
   

3. Agora você pode acessar as APIs da sua organização através do gateway de API privado.

   Nota

   Além de acessar as APIs da organização com suas URLs de API privadas, você ainda pode usar as URLs do Jitterbit. Para bloquear o acesso às URLs do Jitterbit, uma operação pode primeiro confirmar que uma URL é do gateway de API privado e cancelar se não for. O seguinte é um exemplo de um teste na região NA (para as regiões EMEA e APAC, substitua jitterbit.eu ou jitterbit.cc conforme apropriado):

   <trans>
   if( index($jitterbit.api.request.headers.fulluri,'jitterbit.net') >0,
       $jitterbit.api.response = 'Public API gateway not permitted';
       CancelOperationChain($jitterbit.api.response);
   )
   </trans>
   

   Uma inicialização bem-sucedida do gateway de API privado se parece com o seguinte:

   Exemplo de inicialização

   . . .
   nginx: [alert] [lua] startup.lua:0: ():
          ___ ___  ___  __   __    ___
      | |  |   |  |__  |__) |__) |  |
   \__/ |  |   |  |___ |  \ |__) |  |
              API gateway
   
   Version: x.x.x.x
   Build Date: 20XX/XX/XX 00:00
   
   Loading Libraries...
   Libraries loaded successfully!
   
   Loading configuration...
   Configuration file:  /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml
   Configuration file successfully loaded, parsing values...
   
   ************************************************************
   
   InfluxDB output not configured.
   Loggly output not configured.
   ELK output not configured.
   
   Configuration parsing successful!
   
   Doing startup checks...
   
   Checks completed, no errors.
   
   ------------------------------------------------------------
   
   Jitterbit Services URL: https://services.jitterbit.net/apis
   Gateway will login as: gatewayuser
   Organization ID set to: 123456
   
   Current Time: 20XX-XX-XX 00:00:00
   Gateway Startup Successful!
   
   Gateway server started
   

(Opcional) Alterar protocolos e cifras SSL suportados

Se necessário, os protocolos e cifras SSL suportados podem ser alterados no arquivo de configuração local /usr/local/openresty/nginx/conf/onpremise.conf usando as diretivas ssl_protocols e ssl_ciphers, respectivamente. Isso pode ser feito para remover o suporte a um protocolo ou cifra padrão, dependendo dos seus requisitos de segurança. Por exemplo:

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

(Opcional) Alterar o prefixo da URL de carga útil para suporte ao ALB

Se estiver configurando um ambiente de múltiplos gateways atrás de um balanceador de carga de aplicativo (ALB), como o AWS ALB, o protocolo usado para o roteamento de carga útil pode ser alterado no arquivo /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml modificando a diretiva payloadurlprefix. Por exemplo:

payloadurlprefix: https://

Teste o gateway de API privado

Para testar o gateway, siga estas etapas:

1. Configure um API Manager API válido na organização associada ao gateway de API privado, e uma URL de serviço API do API Manager no formato https://JBExample123456.jitterbit.net/Development/1/customer.

2. Teste a API. Se estiver funcionando corretamente, use-a para testar uma URL de API privada substituindo o domínio e subdomínios do Jitterbit pelos seus, mantendo o mesmo caminho. (Se for uma configuração de proxy, acrescente ?debug à URL.)

   Exemplo

   Se seu subdomínio for mysubdomain e o domínio for example, a URL base se torna mysubdomain.example.com, e você deve alterar a URL de serviço API https://JBExample123456.jitterbit.net/Development/1/customer para a URL de API privada https://mysubdomain.example.com/Development/1/customer. Para testar uma URL de API privada de proxy https://mysubdomain.example.com/Development/1/customer, use https://mysubdomain.example.com/Development/1/customer?debug. Se bem-sucedido, a saída será Proxy enabled: PROXY_URI, onde PROXY_URI é o valor fornecido durante a configuração.

Auto-teste do gateway de API privado

Para executar um auto-teste do gateway, use a opção --test para o comando jitterbit-api-gateway-config. Após um login bem-sucedido, ele executa automaticamente uma série de testes para garantir a configuração adequada. Esses testes incluem a importação de um projeto e API integrados, e a chamada da API através do gateway. (Uma URL de API deve estar disponível na sua assinatura para que o auto-teste seja bem-sucedido.)

Atualizar um gateway de API privado

Para atualizar um gateway de API privado para uma versão mais recente, siga estas etapas:

1. Baixe a versão mais recente do software do gateway de API privado através da página de Downloads. (Se necessário, versões anteriores do software podem ser obtidas através do suporte Jitterbit.)

   Dica

   A atualização de um gateway de API privado para uma versão mais recente pode ser feita sem desinstalar a versão anterior do gateway, mesmo ao atualizar de uma versão 10.x para uma versão 11.x.

2. Crie um backup do arquivo de configuração do gateway de API privado /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml.

3. Se você fez alterações nos protocolos e cifras SSL suportados, crie um backup do arquivo de configuração on-premise /usr/local/openresty/nginx/conf/onpremise.conf.

4. Ao atualizar de uma versão do gateway de API privado 10.61 ou anterior, crie um backup dos arquivos de certificado SSL. Os arquivos de certificado SSL do gateway de API privado estão localizados nestes diretórios:

   /usr/local/openresty/nginx/ssl/nginx.crt
   /usr/local/openresty/nginx/ssl/nginx.key
   

   Nota

   Para versões do gateway de API privado 10.62 ou posteriores, não é necessário fazer um backup ou copiar os arquivos de certificado SSL. Esses arquivos são mantidos durante uma atualização.

5. Siga os passos de instalação. (Os comandos para atualizar um gateway de API privado são os mesmos da instalação.)

6. Copie o backup do arquivo de configuração do gateway de API privado, o arquivo de configuração on-premise (se aplicável) e os arquivos de certificado SSL (se aplicável) para a nova instalação do gateway de API privado.

7. (Opcional) Execute jitterbit-api-gateway-config para fazer alterações de configuração adicionais. Você pode fazer isso se estiver usando novas configurações que estão disponíveis em uma versão mais recente do gateway de API privado.

8. Execute este comando para reiniciar o gateway de API privado:

   jitterbit-api-gateway-config -s restart
   

Desinstalar um gateway de API privado

Para desinstalar um gateway de API privado, execute estes comandos:

yum remove jitterbit-api-gateway
rm -rf /usr/local/jitterbit-api-gateway/
rm -rf /usr/local/openresty/
rm -rf /usr/local/hostedfiles/

apt-get remove jitterbit-api-gateway
apt-get purge jitterbit-api-gateway
rm -rf /usr/local/jitterbit-api-gateway/
rm -rf /usr/local/openresty/
rm -rf /usr/local/hostedfiles/

Comando jitterbit-api-gateway-config

O comando jitterbit-api-gateway-config permite gerenciar um gateway de API privado Jitterbit.

Sinopse

jitterbit-api-gateway-config [OPÇÕES]

Opções

• -h, --help: Exibir uma mensagem de ajuda e sair.

• -u USER, --user=USER: Nome de usuário do Jitterbit Harmony.

• -p PASSWORD, --password=PASSWORD: Senha do Jitterbit Harmony.

• -o ORGANIZATION_ID, --organizationId=ORGANIZATION_ID: ID da organização do Jitterbit Harmony.

• -e ServiceUrl, --serviceUrl=ServiceUrl: URL dos Serviços Jitterbit.

• -s COMMAND, --server=COMMAND: Valores válidos para COMMAND:

  • start: Iniciar o gateway.

  • stop: Parar o gateway.

  • restart: Reiniciar o gateway.

• -d, --dns: Configurar interativamente os servidores DNS.

• --proxyEnabled=true | false: Habilitar (true) ou desabilitar (false) um proxy.

• --proxyUri=PROXY_URI: URI do servidor proxy.

• --proxyUser=PROXY_USER: Nome de usuário do servidor proxy.

• --proxyPassword=PROXY_PASSWORD: Senha do servidor proxy.

• -t, --test: Executar testes automáticos.

• --debug: Habilitar saída de depuração para os testes automáticos.

• --noColor: Desabilitar cores de texto no terminal.