Saltar al contenido

Instalar 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 de API privada anteriormente se conocía como puerta de enlace de API local Jitterbit.

Prerrequisitos

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 y utiliza una de estas distribuciones:

    Nota

    Es posible que se puedan 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 de 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 de API privada, ya que las cargas útiles de solicitud y respuesta se almacenan en el servidor durante las transacciones de API.

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

    Advertencia

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

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

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

    • No utilice un certificado autofirmado.
    • El certificado debe constar de dos archivos: un archivo CRT (.crt) para el certificado firmado y CLAVE (.key) para la clave privada.
    • Estos archivos de certificado deben estar en el formato PEM que un servidor NGINX puede comprender.
    • 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, use 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 en proveedores como Let's Encrypt.

  • A partir de la versión 10.3 de Harmony, de manera predeterminada, la puerta de enlace de 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 API privada.

Instalar una Puerta de Enlace API Privada

Después de confirmar los prerrequisitos anteriores, 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 exclusivamente al uso de la puerta de enlace de 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 el nodo de cómputo 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 poder iniciar sesión en la máquina de forma remota.

  2. En muchos ambientes Linux, el firewall bloquea automáticamente el puerto HTTPS (443) necesario 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 a la máquina por SSH mediante un cliente SSH.

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

Para instalar el software de puerta de enlace de API privada, inicie sesión en su máquina a través de SSH y ejecute los comandos correspondientes a 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 de archivo según corresponda:

Para instalar una API gateway privada versión 10.61 o anterior (en REHL o Amazon Linux AMI), 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 API gateway privada versión 10.62 o posterior (en REHL o Amazon Linux AMI), 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 API gateway 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 API gateway 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: Instalar los Archivos del Certificado SSL

La puerta de enlace de API privada requiere que los archivos de certificado de la máquina tengan un 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 de certificado SSL, deberá agregarlos al almacén de claves de Jitterbit Java 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 comandos:

/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 necesaria en la línea de comandos o, iniciando el comando sin ninguna opción, ingresar a una sesión interactiva que prepara el archivo de configuración de la puerta de enlace de 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 de API privada /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml.

Al configurar una puerta de enlace de 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 de 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 se expongan en texto sin formato y no tiene como objetivo proporcionar un alto nivel de seguridad. Asegúrese de que el archivo de configuración se almacene de manera segura.

La primera vez que configure una puerta de enlace de API privada con credenciales de Harmony, se creará automáticamente un nuevo usuario de puerta de enlace de API independiente con una contraseña que no caduque en la organización como miembro del rol_Administrator_. Este usuario no está asociado con una dirección de correo y no puede iniciar sesión en el portal de Harmony; este usuario es solo para fines de puerta de enlace de API. Las credenciales de este usuario se agregan a la gatewayconfig.yaml archivo.

Desde la versión 11.32 de API Gateway, si reconfigura la puerta de enlace, verá una pregunta adicional:

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

Si respondes N(o presione Enter para obtener la respuesta predeterminada), se utilizan las credenciales de usuario existentes. Si responde Y, se crea un nuevo usuario.

Estos usuarios de la puerta de enlace API se muestran en la Management Console Administración de usuarios página y están en el formato de <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 _1.

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 del proxy (si se debe habilitar la configuración del 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 en cuanto a la última pregunta, la puerta de enlace API privada debería comenzar a ejecutarse.

Si la instalación se realizó correctamente, ahora puede acceder a las APIs de la organización mediante la puerta de enlace de API privada. No es necesario realizar ninguna otra configuración; ahora 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 las URLs de API privadas, aún puede usar 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 de API privada y cancelar si no es así. Aquí hay un ejemplo de prueba en la región NA (para las regiones EMEA y APAC, sustituya jitterbit.eu o jitterbit.cc según corresponda):

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

Una startup exitosa de API gateway privada se parece a esto:

. . .
nginx: [alerta] [lua] startup.lua:0: ():
       ____  ___  __   __    ___
   | |  |   |  |__  |__) |__) |  |`FINAL DE LA MESA`
\__/ |  |   |  |___ |  \ |__) |  |`FINAL DE LA 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 funcione como se espera.

Al probar la puerta de enlace de API privada, debe tener una API de API Manager 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 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 comprobar que la configuración de un proxy funciona, añada ?debug a la URL:

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

El resultado se muestra:

Proxy enabled: {proxyUri}

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

Autoprueba de la Puerta de Enlace de API Privada

La puerta de enlace API privada incluye una prueba automática, a la que se puede acceder mediante el --test opción en la línea de comando.

Después de iniciar sesión correctamente, la prueba automática se ejecuta a través de una serie de pruebas automáticas que incluyen la importación de un proyecto y una API integrados y, luego, la llamada a la API a través de la puerta de enlace para garantizar la configuración adecuada. Debe haber una URL de API disponible en su suscripción para que la prueba automática sea exitosa.

Reiniciar una Puerta de Enlace API Privada

Es posible que deba detener, iniciar o reiniciar la puerta de enlace de API privada para realizar cambios de configuración adicionales, realizar actualizaciones o identificar y solucionar problemas. Para ello, utilice 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 está ejecutando actualmente en su máquina, utilice este comando:

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

El resultado se muestra:

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

Se puede actualizar una puerta de enlace de API privada a una versión posterior sin desinstalar la versión de puerta de enlace anterior, 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 de API privada a través de Descargas página. Si es necesario, se pueden obtener versiones anteriores del software en Soporte Jitterbit.

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

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

  3. Al actualizar desde una versión 10.61 o anterior de una puerta de enlace de API privada, cree una copia de seguridad de los archivos de certificado SSL. Los archivos de certificado SSL de la puerta de enlace de 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 de 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 que se utilizan para actualizar una puerta de enlace de API privada son los mismos que los que se utilizan durante la instalación inicial. Siga las instrucciones del Paso 2: Instalar el software de la puerta de enlace de API privada.

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

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

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

    Para conocer todas las opciones de configuración, consulte Paso 4: Configurar la puerta de enlace de 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 de API privada puede encontrar errores en las versiones más nuevas de la puerta de enlace de API privada. En estos casos, asegúrese de que el paso 5 de la actualización se haya realizado correctamente.

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 versión 10.62 o posterior de la puerta de enlace de API privada, ejecute este comando:

apt-get purge jitterbit-api-gateway

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

yum remove jitterbit-api-gateway

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

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