Ir para o conteúdo

Instalar um gateway de API privada da Jitterbit no Linux

Visão geral

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

Requisitos do sistema

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

Hardware

CPU Intel x86_64 (amd64) quad-core, 8 GB de memória.
Disco 50 GB, NTFS (Windows), ext2, ext4, xfs (Linux), velocidade de transferência de 50 MB/s.
Rede Conexão de internet de alta velocidade.

Importante

A velocidade e o espaço do disco rígido são componentes críticos do gateway de API privada, pois os payloads de requisição e resposta são armazenados no servidor durante transações de API.

Sistemas operacionais

OS Versão Versões do gateway de
API privada suportadas
Linux Red Hat Enterprise Linux 9 Versões atualmente suportadas
Amazon Linux 2023 Versões atualmente suportadas
Ubuntu 24.04 LTS Versões atualmente suportadas
Docker Versões atualmente suportadas

Nota

Distribuições adicionais não listadas acima podem funcionar, mas não são suportadas pela Jitterbit.

Rede

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

    Desde a versão 12.13 do gateway de API privada, o nome de domínio pode conter caracteres multibyte. O comando jitterbit-api-gateway-config converte o nome de domínio para Punycode para validação de DNS e para o teste automático, portanto registre o formulário Punycode do nome de domínio no seu DNS ou arquivo de hosts. Solicite o certificado SSL também para o formulário Punycode.

  • Um certificado SSL válido para o subdomínio, de uma autoridade de certificação reconhecida; não use um certificado auto-assinado.

    O certificado deve ser composto por dois arquivos: um arquivo CRT (.crt) para o certificado assinado e KEY (.key) para a chave privada. Esses devem estar no formato PEM que um servidor NGINX possa compreender. (À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 sejam combinados em um único arquivo PFX. Nesse caso, use OpenSSL para extrair os dois arquivos.

    Dica

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

  • Conectividade SSH.

Contas

Seu Harmony deve ter uma função com permissão de 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 ótimo.

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

    • Red Hat Enterprise Linux (RHEL): Se baseado em nuvem, use um nó Compute 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:

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

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

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

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

  2. Execute esses 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 de versão baixado:

    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
    
    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
    
    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 do logrotate para logs do NGINX:

    /etc/logrotate.d/nginx
    

    (Opcional) Abra este arquivo, revise as configurações e ajuste conforme 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
    
  5. Adicione os arquivos de certificado ao Java KeyStore do Jitterbit.

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

    jitterbit-api-gateway-config
    

    Dica

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

    Observações importantes

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

    • A primeira vez que você configura 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 uma função Administrador. Este usuário não está associado a um endereço de e-mail, não pode fazer login no portal Harmony e é apenas para o gateway de API. As credenciais deste usuário são adicionadas ao arquivo gatewayconfig.yaml.

    • Desde a versão 11.32 do gateway de API, ao reconfigurar o gateway, você é feito a seguinte pergunta adicional:

      Would you like to generate a new Gateway credentials and overwrite existing ones? (y/N):
      

      Se você responder N, as credenciais de usuário existentes serão usadas. Se você responder Y, um novo usuário será criado.

    • Os usuários do gateway de API são mostrados 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 será anexado com um sublinhado e um número incrementado, como _1.

    Exemplo de saída
    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)?
    . . .
    
  7. Agora você pode acessar as APIs da sua organização por meio 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 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 é semelhante ao 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 SSL e cifras suportados

Se necessário, os protocolos SSL e cifras 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 suporte a um protocolo ou cifra padrão dependendo de 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;

Importante

Se forem feitas alterações no arquivo de configuração local, crie um backup do arquivo. As alterações não persistem ao atualizar um gateway de API privado.

(Opcional) Alterar o número máximo de níveis de subdomínio suportados para um FQDN personalizado

O nome de domínio totalmente qualificado (FQDN) personalizado de um gateway de API privado pode conter vários níveis de subdomínio, como mysubdomain.department.region.example.com. Desde a versão 12.9 do gateway de API privado, um gateway de API privado oferece suporte a FQDNs com até 10 níveis de subdomínio por padrão. A chave MaxDomainParts não está presente em gatewayconfig.yaml por padrão.

Se seu FQDN personalizado exigir mais de 10 níveis de subdomínio, adicione manualmente a chave MaxDomainParts ao arquivo com o número de níveis necessários. Por exemplo:

MaxDomainParts: 15

Após atualizar gatewayconfig.yaml, execute jitterbit-api-gateway-config para aplicar a alteração.

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

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

payloadurlprefix: https://

Testar o gateway de API privado

Para testar o gateway, siga estas etapas:

  1. Configure uma API do API Manager válida na organização associada ao gateway de API privado e uma URL de serviço de 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 os subdomínios do Jitterbit pelos seus próprios, 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ê alteraria a URL de serviço de 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, em que PROXY_URI é o valor fornecido durante a configuração.

Autoteste do gateway de API privado

Para executar um autoteste 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. Isso inclui importar um projeto integrado e uma API, e chamar a API através do gateway. (Uma URL de API deve estar disponível em sua assinatura para que o autoteste seja bem-sucedido.)

Nota

A API é criada com a opção SSL only ativada, portanto o acesso à URL do gateway é testado apenas usando HTTPS. Para permitir acesso via HTTP, você pode desativar a opção SSL only na configuração da API após a criação da API de teste.

Atualizar um gateway de API privado

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

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

    Dica

    A atualização de um gateway de API privado para uma versão posterior pode ser feita sem desinstalar a versão anterior do gateway, até mesmo ao atualizar de 10.x para 11.x ou de 11.x para 12.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 SSL e cifras suportados, crie um backup do arquivo de configuração local /usr/local/openresty/nginx/conf/onpremise.conf.

  4. Ao atualizar de um gateway de API privado versão 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 o gateway de API privado versão 10.62 ou posterior, não é necessário fazer um backup ou copiar os arquivos de certificado SSL. Esses arquivos são retidos durante uma atualização.

  5. Siga as etapas de instalação. (Os comandos para atualizar um gateway de API privado são os mesmos que para a instalação.)

  6. Copie o backup do arquivo de configuração do gateway de API privado, arquivo de configuração local (se aplicável) e 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 disponíveis em uma versão posterior 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 da Jitterbit.

Sinopse

jitterbit-api-gateway-config [OPTIONS]

Opções

  • -h, --help: Exibe uma mensagem de ajuda e sai.

  • -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 do Jitterbit Services.

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

    • start: Inicia o gateway.

    • stop: Para o gateway.

    • restart: Reinicia o gateway.

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

  • --proxyEnabled=true | false: Ativa (true) ou desativa (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 autotestes.

  • --debug: Ativar saída de depuração para autotestes.

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