Saltar al contenido

Instale una Puerta de Enlace API Privada en Linux

Descripción General

Estas son las instrucciones para instalar y configurar una puerta de enlace API privada.

Nota

La puerta de enlace API privada se conocía anteriormente como puerta de enlace API local de Jitterbit.

Requisitos Previos

Para instalar una puerta de enlace API privada, el hardware y el software deben cumplir estos requisitos:

  • Servidor Linux que ejecuta un sistema operativo de 64 bits utilizando una de estas distribuciones:

    Nota

    Es posible utilizar otras distribuciones de Linux, pero actualmente Jitterbit no las admite. Como cada distribución de Linux puede variar, las instrucciones para instalar la puerta de enlace API privada en otras distribuciones de Linux pueden ser diferentes a las descritas en esta página.

  • Estos son los requisitos mínimos de hardware y máquinas virtuales para una puerta de enlace API privada:

    • Procesador de cuatro núcleos

    • 8 GB de RAM

    • 50 GB de espacio disponible en el disco duro

    • Velocidad de transferencia de 50 megabytes/segundo en el disco duro

    • Conexión a Internet de alta velocidad

    Precaución

    La velocidad y el espacio del disco duro son componentes críticos de la puerta de enlace API privada, ya que las cargas útiles de solicitud y respuesta se almacenan en el servidor durante las transacciones API.

  • Configuración óptima del sistema y ambiente general ejecutando la puerta de enlace API privada.

    Advertencia

    Si no se configura de manera óptima, pueden surgir problemas esporádicos e impredecibles debido a problemas de red, E/S de disco deficientes, problemas de memoria limitada o insuficiente, espacio en disco limitado o insuficiente, fallas de energía o reinicios abruptos del sistema..

  • Un subdominio o nombre de dominio, apuntado al servidor (por ejemplo, mysubdomain.example.com).

  • Un certificado SSL válido para el subdominio, de una autoridad certificadora reconocida:

    • No utilice un certificado autofirmado.
    • El certificado debe constar de dos archivos: un archivo CRT (.crt) para el certificado firmado y la CLAVE (.key) para la clave privada.
    • Estos archivos de certificado deben estar en el formato PEM que un servidor NGINX puede entender.
    • A veces la extensión de los archivos es diferente; a menudo las extensiones CRT, PEM y CER son intercambiables.
    • También es posible que los dos archivos se combinen en un solo archivo PFX; en ese caso, utilice OpenSSL para extraer los dos archivos.
    • ¡Recuerde controlar las fechas de vencimiento de los certificados!
    • Comuníquese con su proveedor de certificados para obtener información adicional.
    • Los certificados SSL gratuitos están disponibles a través de proveedores como Let's Encrypt.
  • A partir de la versión 10.3 de Harmony, de forma predeterminada, la puerta de enlace API privada ya no admite Transport Layer Security (TLS) 1.0 (consulte actualización de compatibilidad de la versión TLS). Para cambiar esta configuración predeterminada, comuníquese con soporte de Jitterbit.

  • Para utilizar una configuración de proxy, se requiere la versión 10.30.1 o posterior de la puerta de enlace API privada.

Instalar una Puerta de Enlace API Privada

Después de confirmar los requisitos previos, siga estos pasos para configurar una puerta de enlace API privada:

Paso 1: Configurar la Máquina de Puerta de Enlace API

  1. Configure una nueva máquina Linux. Se recomienda que la máquina esté dedicada únicamente al uso de la puerta de enlace API privada.

    Estas recomendaciones adicionales dependen del sistema operativo:

    • Red Hat Enterprise Linux (RHEL)

      Si instala RHEL por primera vez en esta máquina, recomendamos utilizar Compute Node con estas opciones incluidas:

      • Herramientas de depuración
      • Utilidades de monitoreo de hardware
      • Bibliotecas de compatibilidad
      • Herramientas de desarrollo
      • Herramientas de seguridad
    • Ubuntu o Debian

      Si instala Ubuntu o Debian, instálelo con los valores predeterminados e incluya el servidor OpenSSH para que pueda iniciar sesión en la máquina de forma remota.

  2. En muchos ambientes Linux, el firewall bloquea automáticamente el puerto HTTPS (443) requerido para la puerta de enlace API privada.

    Para abrir el puerto HTTPS, utilice estos comandos según corresponda:

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

    o

    64-bit Debian or Ubuntu
    ufw allow 443/tcp
    
  3. Apunte el subdominio o dominio a la dirección IP del servidor.

  4. Confirme que puede acceder mediante SSH a la máquina mediante un cliente SSH.

Paso 2: Instale el Software de Puerta de Enlace API Privada

Para instalar el software de puerta de enlace API privada, inicie sesión en su máquina a través de SSH y ejecute los comandos apropiados para su versión de Linux. El enlace de descarga y el archivo descargado variarán según la versión y se encuentran en su información de registro. Los archivos de descarga también están disponibles a través del Portal Harmony Descargas página. Ajuste las rutas y el nombre del archivo en consecuencia:

Para instalar una puerta de enlace API privada versión 10.61 o anterior (en REHL o AMI de Amazon Linux ), ejecute estos 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 una puerta de enlace API privada versión 10.62 o posterior (en REHL o AMI de Amazon Linux ), ejecute estos 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 una puerta de enlace API privada versión 10.61 o anterior (en Debian o Ubuntu), ejecute estos 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 una puerta de enlace API privada versión 10.62 o posterior (en Debian o Ubuntu), ejecute estos 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

Paso 3: Instale los Archivos del Certificado SSL

La puerta de enlace API privada requiere que los archivos de certificado de la máquina tengan el nombre nginx.crt y nginx.key y debe copiarse en estas ubicaciones:

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

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

Una vez que haya instalado los archivos del certificado SSL, deben agregarse al almacén de claves Java de Jitterbit para su agente privado. Para obtener más información, consulte Agregar certificados al almacén de claves para agentes privados.

Paso 4: Configurar la Puerta de Enlace API Privada

Para completar la instalación, ejecute este comando como root para configurar la puerta de enlace API privada:

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

La puerta de enlace API privada proporciona ayuda en la línea 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

Puede proporcionar toda la información requerida en la línea de comando o, al iniciar el comando sin ninguna opción, ingresar a una sesión interactiva que prepara el archivo de configuración de la puerta de enlace API privada y luego ofrece iniciar la puerta de enlace. La configuración ingresada se captura en el archivo de configuración de la puerta de enlace API privada en este directorio:

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

Al configurar una puerta de enlace API privada, el nombre de usuario y la contraseña de Harmony deben estar asociados con un miembro de un rol con permiso_Admin_. El permiso Agent-Install no es suficiente. En el archivo de configuración de la puerta de enlace API privada, los campos de nombre de usuario y contraseña de Harmony se almacenan cifrados, mientras que el nombre de usuario y la contraseña del servidor proxy se almacenan codificados en Base64. Esto es para evitar que las credenciales del proxy queden expuestas en texto claro y no pretende proporcionar un alto nivel de seguridad. Asegúrese de que el archivo de configuración esté almacenado de forma segura.

Cada vez que configura una puerta de enlace API privada con credenciales de Harmony, se crea automáticamente en la organización un nuevo usuario de puerta de enlace API independiente con una contraseña que no vence como miembro de la rol_Administrador_. Este usuario no está asociado con una dirección de correo y no puede iniciar sesión en el Portal Harmony; este usuario es solo para fines de puerta de enlace API.

Estos usuarios de API Gateway se muestran en la Management Console Administración de usuarios y tienen el formato GatewayUser_\<orgID>_\<ID>. Si el mismo usuario reconfigura la puerta de enlace en la misma organización, al nombre del usuario de la puerta de enlace se le añade un guión bajo y un número incrementado, como por ejemplo _1:

adjunto

El resultado de la utilidad de configuración es similar al siguiente. Cuando se le solicite, ingrese la información requerida, como su nombre de usuario y contraseña de Harmony, Región de Harmony, información de proxy (si se va a habilitar la configuración de proxy), URL de servicios (si es diferente a la predeterminada), ID de la organización (si es diferente a la predeterminada para esa cuenta) y configuración deseada 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)?
. . .

si respondes Y A la última pregunta, la puerta de enlace API privada debería comenzar a ejecutarse.

Si la instalación fue exitosa, ahora puede acceder a las APIs de la organización mediante la puerta de enlace API privada. No es necesaria ninguna configuración adicional; Ahora se debería poder acceder a todas las APIs de la organización mediante la puerta de enlace de API privada.

Nota

Además de acceder a las APIs de la organización con sus URLs de API privadas, aún puede utilizar las URLs de Jitterbit. Para bloquear el acceso a las URLs de Jitterbit, una operación primero puede confirmar que una URL proviene de la puerta de enlace API privada y cancelarla si no. A continuación se muestra un ejemplo de prueba en la región NA (para las regiones EMEA y APAC, sustituya jitterbit.eu o jitterbit.cc según sea apropiado):

<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 obtener ayuda, comuníquese con soporte de Jitterbit.

Un inicio exitoso de una puerta de enlace API privada es similar a este:

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

Paso 5: Pruebe la Puerta de Enlace API Privada

Una vez instalada la puerta de enlace API privada, se debe probar para garantizar que funciona como se esperaba.

Al probar la puerta de enlace API privada, debe tener una API Manager API válida en la organización asociada con la puerta de enlace API privada.

Pruebe la API utilizando un API Manager URL del servicio API en este formato:

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

Si la API funciona correctamente, se puede utilizar para probar una URL de API privada.

Usando su subdominio y dominio, reemplace el dominio y el subdominio de Jitterbit, conservando la misma ruta.

Usando el subdominio (mysubdomain) y dominio (example) como mysubdomain.example.com, la URL del servicio API se cambiaría a esta URL API privada:

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

Para probar que una configuración de proxy funciona, agregue ?debug a la URL:

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

Se muestra la salida:

Proxy enabled: {proxyUri}

Dónde {proxyUri} es el valor proporcionado durante la configuración.

Autoprueba de Puerta de Enlace API Privada

La puerta de enlace API privada incluye una autoprueba, a la que se puede acceder mediante el --test opción en la línea de comando. Después de un inicio de sesión exitoso, la autoprueba se ejecuta a través de una batería de pruebas automáticas que incluye importar un proyecto integrado y una API y luego llamar a la API a través de la puerta de enlace para garantizar la configuración adecuada.

Reiniciar una Puerta de Enlace API Privada

Es posible que deba detener, iniciar o reiniciar la puerta de enlace API privada para realizar cambios de configuración adicionales, actualizar o identificar y solucionar problemas. Para hacerlo, use la utilidad de configuración y estas opciones:

# 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

Actualizar una Puerta de Enlace API Privada

Para encontrar la versión de la puerta de enlace API privada que se ejecuta actualmente en su máquina, utilice este comando:

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

Se muestra la salida:

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

La actualización de una puerta de enlace API privada a una versión posterior se puede realizar sin desinstalar la versión anterior de la puerta de enlace, incluso cuando se actualiza de una versión 10.x a una 11.x.

Para actualizar una puerta de enlace API privada a una versión posterior, siga estos pasos:

  1. Descargue la última versión del software de puerta de enlace API privada a través de Descargas página. Si es necesario, se pueden obtener versiones anteriores del software en Soporte de Jitterbit.

  2. Cree una copia de seguridad del archivo de configuración de la puerta de enlace API privada existente. El archivo de configuración de la puerta de enlace API privada se encuentra en este directorio:

    /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml
    
  3. Al actualizar desde una puerta de enlace API privada versión 10.61 o anterior, cree una copia de seguridad de los archivos del certificado SSL. Los archivos de certificado SSL de la puerta de enlace API privada se encuentran en estos directorios:

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

    Nota

    Para la versión 10.62 o posterior de la puerta de enlace API privada, no es necesario realizar una copia de seguridad ni copiar los archivos del certificado SSL. Estos archivos se conservan durante una actualización.

  4. Los comandos utilizados para actualizar una puerta de enlace API privada son los mismos que se utilizan durante la instalación inicial. Siga las instrucciones para Paso 2: Instale el software de puerta de enlace API privada.

  5. Copie la copia de seguridad del archivo de configuración de la puerta de enlace API privada y los archivos de certificado SSL (si corresponde) a la nueva instalación de la puerta de enlace API privada.

  6. Opcionalmente, ejecute la herramienta de configuración de línea de comando para realizar cambios de configuración adicionales. Es posible que desee hacer esto si está utilizando nuevos ajustes de configuración que están disponibles en una versión posterior del software de puerta de enlace API privada.

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

    Para todas las opciones de configuración, consulte Paso 4: Configurar la puerta de enlace API privada.

  7. Reinicie la puerta de enlace API privada:

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

Nota

Después de una actualización, el archivo de configuración de la puerta de enlace API privada puede encontrar errores en versiones más nuevas de la puerta de enlace API privada. En estos casos, asegúrese de que el paso 5 de la actualización sea exitoso.

Desinstalar una Puerta de Enlace API Privada

Utilice este comando para desinstalar una puerta de enlace API privada en distribuciones de Linux basadas en RPM:

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

Utilice este comando para desinstalar una puerta de enlace API privada en distribuciones de Linux basadas en Debian:

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

Para completar la desinstalación, ejecute estos comandos:

Para distribuciones de Linux basadas en Debian que utilizan la puerta de enlace API privada versión 10.62 o posterior, ejecute este comando:

apt-get purge jitterbit-api-gateway

Para distribuciones de Linux basadas en RPM que utilizan la puerta de enlace API privada versión 10.62 o posterior, ejecute este comando:

yum remove jitterbit-api-gateway

Para distribuciones de Linux basadas en RPM y Debian (todas las versiones de puerta de enlace API privada), ejecute estos comandos:

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