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-configconverte 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 --reloadufw 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:
-
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.
-
-
Execute esses comandos para sua combinação de sistema operacional e versão do gateway, substituindo
x.x.x.x(.deb) oux.x.x-x(.rpm) pelo número de versão baixado:yum update yum install jitterbit-api-gateway-x.x.x-x.x86_64.rpmyum 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.rpmapt-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.debapt-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.debapt-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 -
Desde a versão 11.49, o processo de instalação adiciona o seguinte arquivo de configuração do
logrotatepara logs do NGINX:/etc/logrotate.d/nginx(Opcional) Abra este arquivo, revise as configurações e ajuste conforme necessário.
-
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 -
Adicione os arquivos de certificado ao Java KeyStore do Jitterbit.
-
Execute o seguinte comando e responda às perguntas:
jitterbit-api-gateway-configDica
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ê responderY, 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)? . . . -
-
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.euoujitterbit.ccconforme 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:
-
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. -
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
mysubdomaine o domínio forexample, a URL base se tornamysubdomain.example.com, e você alteraria a URL de serviço de APIhttps://JBExample123456.jitterbit.net/Development/1/customerpara a URL de API privadahttps://mysubdomain.example.com/Development/1/customer. Para testar uma URL de API privada de proxyhttps://mysubdomain.example.com/Development/1/customer, usehttps://mysubdomain.example.com/Development/1/customer?debug. Se bem-sucedido, a saída seráProxy enabled: PROXY_URI, em quePROXY_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:
-
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.
-
Crie um backup do arquivo de configuração do gateway de API privado
/usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml. -
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. -
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.keyNota
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.
-
Siga as etapas de instalação. (Os comandos para atualizar um gateway de API privado são os mesmos que para a instalação.)
-
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.
-
(Opcional) Execute
jitterbit-api-gateway-configpara 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. -
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 paraCOMMAND:-
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.