Ir para o conteúdo

Instale um Gateway Privado

Visão Geral

Estas são as instruções para instalar e configurar um Gateway de API Privado.

Nota

O Gateway de API Privado era anteriormente conhecido como Jitterbit On-Premises Gateway de API.

Pré-requisitos

Para instalar um Gateway de API Privado, o hardware e o software devem atender a estes requisitos:

  • Servidor Linux executando um sistema operacional de 64 bits usando uma destas distribuições:

    Nota

    Pode ser possível usar outras distribuições Linux, mas estas não são atualmente suportadas pelo Jitterbit. Como cada distribuição do Linux pode variar, as instruções para instalação do Gateway de API Privado em outras distribuições do Linux podem ser diferentes das descritas nesta página.

  • Estes são os requisitos mínimos de hardware e máquinas virtuais para um Gateway de API Privado:

    • Processador quad-core

    • 8 GB de RAM

    • 50 GB de espaço disponível no disco rígido

    • Taxa de transferência de 50 megabytes/segundo no disco rígido

    • Conexão de Internet de alta velocidade

    Cuidado

    A velocidade e o espaço do disco rígido são componentes críticos do Gateway de API Privado, já que as cargas úteis de solicitação e resposta são armazenadas no servidor durante as transações da API.

  • Configuração ideal do sistema e do ambiente geral executando o Gateway de API Privado.

    Aviso

    Se não for configurado de maneira ideal, problemas esporádicos e imprevisíveis podem resultar de problemas de rede, E/S de disco deficiente, problemas de memória limitada ou sem memória, espaço em disco limitado ou sem espaço em disco, falhas de energia ou reinicializações abruptas do sistema.

  • 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 de certificação reconhecida:

    • Não use 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.
    • Esses arquivos de certificado devem estar no formato PEM que um servidor NGINX posso entender.
    • Às vezes as extensões dos arquivos são diferentes; muitas vezes 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.
    • Lembre-se de monitorar as datas de validade dos certificados!
    • Entre em contato com seu fornecedor de certificado para obter informações adicionais.
    • Certificados SSL gratuitos estão disponíveis em provedores como Let's Encrypt.

  • A partir do Harmony versão 10.3, por padrão, o Gateway de API Privado não oferece mais suporte ao Transport Layer Security (TLS) 1.0 (consulte Atualização de compatibilidade de versão do TLS). Para alterar esta configuração padrão, entre em contato com Suporte Jitterbit.

  • Para usar uma configuração de proxy, é necessário o Gateway de API Privado versão 10.30.1 ou posterior.

Instale um Gateway de API Privado

Depois de confirmar os pré-requisitos forem atendidas, siga estas etapas para configurar um Gateway de API Privado:

Etapa 1: Configurar a Máquina Gateway de API

  1. Configure uma nova máquina Linux. Recomenda-se que a máquina seja dedicada apenas para uso pelo Gateway de API Privado.

    Estas recomendações adicionais dependem do sistema operacional:

    • Red Hat Enterprise Linux (RHEL)

      Se estiver instalando o RHEL pela primeira vez nesta máquina, recomendamos usar o Compute Node com estas opções incluídas:

      • Ferramentas de depuração
      • Utilitários de monitoramento de hardware
      • Bibliotecas de compatibilidade
      • Ferramentas de Desenvolvimento
      • Ferramentas de segurança

    • Ubuntu ou Debian

      Se estiver instalando Ubuntu ou Debian, instale com os padrões e inclua o servidor OpenSSH para que você possa fazer login na máquina remotamente.

  2. Em muitos ambientes Linux, o firewall bloqueia automaticamente a porta HTTPS (443) necessária para o Gateway de API Privado.

    Para abrir a porta HTTPS, use estes comandos conforme apropriado:

    64-bit RHEL or Amazon Linux AMI
    firewall-cmd --zone=public --add-port=443/tcp --permanent
firewall-cmd --reload

    ou

    64-bit Debian or Ubuntu
    ufw allow 443/tcp

  3. Aponte o subdomínio ou domínio para o endereço IP do servidor.

  4. Confirme se você pode usar SSH na máquina usando um cliente SSH.

Etapa 2: Instalar o Software Gateway de API Privado

Para instalar o software Gateway de API Privado, faça login em sua máquina via SSH e execute os comandos apropriados para sua versão do Linux. O link para download e o arquivo baixado variam dependendo do lançamento e estão nas suas informações de registro. Os arquivos para download também estão disponíveis no Portal Harmony Downloads página. Ajuste os caminhos e o nome do arquivo de acordo:

Para instalar um Gateway de API Privado versão 10.61 ou anterior (em REHL ou Amazon Linux AMI), execute estes comandos:

64-bit RHEL or Amazon Linux AMI Private API Gateway Version 10.61 or Earlier
sudo -i

yum update

cd ~

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x-x.x86_64.rpm

yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
Para instalar um Gateway de API Privado versão 10.62 ou posterior (em REHL ou Amazon Linux AMI), execute estes comandos:

64-bit RHEL or Amazon Linux AMI Private API Gateway Version 10.62 or Later
sudo -i

yum update

cd ~

# To install required dependencies:

yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

# To download and install the Private API Gateway:

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x-x.x86_64.rpm

yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpm
Para instalar um Gateway de API Privado versão 10.61 ou anterior (no Debian ou Ubuntu), execute estes comandos:

64-bit Debian or Ubuntu Private API Gateway Version 10.61 or Earlier
sudo -i

cd ~

# To install required dependencies:

apt-get update

apt-get install libzzip-dev

apt-get install libyaml-dev

apt --fix-broken install

apt install python

# To download and install the API Gateway:

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x.x.amd64.deb

dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb
Para instalar um Gateway de API Privado versão 10.62 ou posterior (no Debian ou Ubuntu), execute estes comandos:

64-bit Debian or Ubuntu Private API Gateway Version 10.62 or Later
sudo -i

cd ~

# To install required dependencies:

apt-get update

apt-get -y install libgeoip-dev

apt --fix-broken install

ln -s /usr/bin/python2.7 /usr/bin/python

# To download and install the API Gateway:

wget https://download.jitterbit.com/xxxx/jitterbit-api-gateway-x.x.x.x.amd64.deb

dpkg --install jitterbit-api-gateway-x.x.x.x.amd64.deb

Etapa 3: Instale os Arquivos do Certificado SSL

O Gateway de API Privado exige que os arquivos de certificado da máquina sejam nomeados nginx.crt e nginx.key e deve ser copiado para estes locais:

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

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

Depois de instalar os arquivos de certificado SSL, eles deverão ser adicionados ao repositório de chaves Jitterbit Java para seu Agente Privado. Para obter mais informações, consulte Adicionando Certificados ao Keystore para Agentes Privados.

Etapa 4: Configurar o Gateway de API Privado

Para concluir a instalação, execute este comando como root para configurar o Gateway de API Privado:

/usr/bin/jitterbit-api-gateway-config

O Gateway de API Privado fornece ajuda na linha de comando:

/usr/bin/jitterbit-api-gateway-config --help

# Output:

Usage: jitterbit-api-gateway-config [options]

Options:
 -h, --help            show this help message and exit
 -u USER, --user=USER  Your Harmony user name (normally your email
                       address)
 -p PASSWORD, --password=PASSWORD
                       Your Harmony password
 -o ORGANIZATION_ID, --organizationId=ORGANIZATION_ID
                       Provide your Organization Id if you have more than one
                       organization
 -e ServiceUrl, --serviceUrl=ServiceUrl
                       Your Jitterbit Services URL (e.g.
                       https://services.jitterbit.net/apis
 -s NGINX_SERVER, --server=NGINX_SERVER
                       Valid values:   start   stop   restart
 -d, --dns             interactively config dns servers
 --proxyEnabled=PROXY_ENABLED
                       Enable (true) or disable (false) a proxy
 --proxyUri=PROXY_URI  When proxy is enabled, the Uri for your proxy server.
                       e.g. http://192.168.1.100:808
 --proxyUser=PROXY_USER
                       Proxy server username
 --proxyPassword=PROXY_PASSWORD
                       Proxy server password
 -t, --test            Run self tests
 --debug               Debug output for Self Tests
 --noColor             Turn off terminal text colors

Você pode fornecer todas as informações necessárias na linha de comando ou, iniciando o comando sem nenhuma opção, entrar em uma sessão interativa que prepara o arquivo de configuração do Gateway de API Privado e, em seguida, oferece para iniciar o gateway. A configuração inserida é capturada no arquivo de configuração do Gateway de API Privado neste diretório:

/usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml

Ao configurar um Gateway de API Privado, o nome de usuário e a senha do Harmony devem estar associados a um membro de uma papel da organização com permissão Admin. A permissão Agent-Install não é suficiente (consulte Permissões e acesso do Harmony). No arquivo de configuração do Gateway de API Privado, os campos de nome de usuário e senha do Harmony são armazenados como criptografados, enquanto o nome de usuário e a senha do servidor proxy são armazenados como codificados em Base64. Isso evita que as credenciais do proxy sejam expostas em texto não criptografado e não se destina a fornecer um alto nível de segurança. Certifique-se de que o arquivo de configuração esteja armazenado de maneira segura.

Cada vez que você configura um Gateway de API Privado usando credenciais do Harmony, um novo usuário separado do Gateway de API com uma senha que não expira é criado automaticamente na organização como membro da papel Administrator. Este usuário não está associado a um endereço e-mail e não pode fazer login no Portal Harmony; este usuário é apenas para fins do Gateway de API.

Esses usuários do Gateway de API são exibidos no Management Console Organizações e estão no formato GatewayUser_\<orgID>_\<ID>. Se o mesmo usuário reconfigurar o gateway na mesma organização, o nome do usuário do gateway será anexado a um sublinhado e a um número incrementado, como _1:

anexo

A saída do utilitário de configuração é semelhante à seguinte. Quando solicitado, insira as informações necessárias, como seu nome de usuário e senha Harmony, região Harmony, informações de proxy (se a configuração de proxy for ativada), URL de serviços (se for diferente do padrão), ID da organização (se for diferente do padrão para essa conta) e configuração desejada para DNS:

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)?
. . .

Se você responder Y até a última pergunta, o Gateway de API Privado deve começar a funcionar.

Se a instalação for bem-sucedida, agora você poderá acessar as APIs da organização usando o Gateway de API Privado. Nenhuma configuração adicional é necessária; todas as APIs da organização agora devem estar acessíveis usando o Gateway de API Privado.

Nota

Além de acessar as APIs da organização com suas URLs de API privadas, você ainda pode usar URLs Jitterbit. Para bloquear o acesso aos URLs do Jitterbit, uma operação pode primeiro confirmar se um URL é do gateway da API privada e cancelar se não for. Aqui está um exemplo de teste na região NA (para regiões EMEA e APAC, substitua jitterbit.eu ou jitterbit.cc como 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>

Para obter assistência, entre em contato com Suporte Jitterbit.

Uma inicialização bem-sucedida do Gateway de API Privado é semelhante a esta:

. . .
nginx: [alerta] [lua] startup.lua:0: ():
       ____  ___  __   __    ___
   | |  |   |  |__  |__) |__) |  |`FIM DA MESA`
\__/ |  |   |  |___ |  \ |__) |  |`FIM DA MESA`
           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

Etapa 5: Testar o Gateway de API Privado

Depois que o Gateway de API Privado estiver instalado, ele deverá ser testado para garantir que esteja funcionando conforme o esperado.

Ao testar o Gateway de API Privado, você deve ter uma API Manager API válida na organização associada ao Gateway de API Privado.

Teste a API usando um API Manager API Service URL neste formato:

https://JBExample123456.jitterbit.net/Development/1/customer

Se a API estiver funcionando corretamente, ela poderá ser usada para testar um URL de API privado.

Usando seu subdomínio e domínio, substitua o domínio e subdomínio Jitterbit, mantendo o mesmo caminho.

Usando o subdomínio (mysubdomain) e domínio (example) como mysubdomain.example.com, o URL do serviço de API seria alterado para este URL de API privado:

https://mysubdomain.example.com/Development/1/customer

Para testar se uma configuração de proxy está funcionando, anexe ?debug para a URL:

https://mysubdomain.example.com/Development/1/customer?debug

A saída é exibida:

Proxy enabled: {proxyUri}

Onde {proxyUri} é o valor fornecido durante a configuração.

Autoteste do Gateway de API Privado

O Gateway de API Privado inclui um autoteste, acessível usando o --test opção na linha de comando. Após um login bem-sucedido, o autoteste é executado por meio de uma bateria de testes automáticos que inclui a importação de um projeto e uma API integrados e, em seguida, a chamada da API por meio do gateway para garantir a configuração adequada.

Reinicie um Gateway de API Privado

Talvez seja necessário parar, iniciar ou reiniciar o Gateway de API Privado para fazer alterações adicionais na configuração, atualizar ou diagnosticar e resolver problemas. Para fazer isso, use o utilitário de configuração e estas opções:

# Stop the Private API Gateway:
/usr/bin/jitterbit-api-gateway-config -s stop

# Start the Private API Gateway:
/usr/bin/jitterbit-api-gateway-config -s start

# Restart the Private API Gateway:
/usr/bin/jitterbit-api-gateway-config -s restart

# Private API Gateway Configuration help:
/usr/bin/jitterbit-api-gateway-config -h

# Configure the Private API Gateway:
/usr/bin/jitterbit-api-gateway-config

# Testing the Private API Gateway by using its self-test:
/usr/bin/jitterbit-api-gateway-config --test

Atualizar um Gateway de API Privado

Para encontrar a versão do Gateway de API Privado atualmente em execução em sua máquina, use este comando:

/usr/bin/jitterbit-api-gateway-config --version

A saída é exibida:

Version: x.x.x.x
Build Date: 20XX/XX/XX 00:00

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

  1. Baixe a versão mais recente do software Gateway de API Privado através do Downloads página. Se necessário, versões mais antigas do software podem ser obtidas em Suporte Jitterbit.

  2. Crie um backup do arquivo de configuração existente do Gateway de API Privado. O arquivo de configuração do Gateway de API Privado está localizado neste diretório:

    /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml

  3. 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 backup ou copiar os arquivos do certificado SSL. Esses arquivos são retidos durante uma atualização.

  4. Os comandos usados para atualizar um Gateway de API Privado são os mesmos usados durante a instalação inicial. Siga as instruções para Etapa 2: Instalar o software Gateway de API Privado.

  5. Copie o backup do arquivo de configuração do Gateway de API Privado e dos arquivos de certificado SSL (se aplicável) para a nova instalação do Gateway de API Privado.

  6. Opcionalmente, execute a ferramenta de configuração de linha de comando para fazer alterações adicionais na configuração. Talvez você queira fazer isso se estiver usando novas definições de configuração disponíveis em uma versão posterior do software Gateway de API Privado.

    /usr/bin/jitterbit-api-gateway-config

    Para todas as opções de configuração, consulte Etapa 4: Configurar o Gateway de API Privado.

  7. Reinicie o Gateway de API Privado:

    /usr/bin/jitterbit-api-gateway-config -s restart

Nota

Após uma atualização, o arquivo de configuração do Gateway de API Privado pode encontrar erros em versões mais recentes do Gateway de API Privado. Nestes casos, certifique-se de que a etapa 5 da atualização foi bem-sucedida.

Desinstalar um Gateway de API Privado

Use este comando para desinstalar um Gateway de API Privado em distribuições Linux baseadas em RPM:

RHEL or Amazon Linux AMI 2
yum remove jitterbit-api-gateway

Use este comando para desinstalar um Gateway de API Privado em distribuições Linux baseadas em Debian:

Debian or Ubuntu
apt-get remove jitterbit-api-gateway

Para concluir a desinstalação, execute estes comandos:

Para distribuições Linux baseadas em Debian usando Gateway de API Privado versão 10.62 ou posterior, execute este comando:

apt-get purge jitterbit-api-gateway

Para distribuições Linux baseadas em RPM que usam o Gateway de API Privado versão 10.62 ou posterior, execute este comando:

yum remove jitterbit-api-gateway

Para distribuições Linux baseadas em RPM e Debian (todas as versões do Gateway de API Privado ), execute estes comandos:

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