Instalar un gateway de API privado de Jitterbit en Linux

Descripción general

Esta página explica cómo instalar, configurar y probar un gateway de API privado.

Requisitos del sistema

Esta sección proporciona los requisitos mínimos para un host de gateway de API.

Hardware

Sistemas operativos

Red

• 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 de certificación reconocida; no utilice un certificado autofirmado.

  El certificado debe consistir en dos archivos: un archivo CRT (.crt) para el certificado firmado, y KEY (.key) para la clave privada. Estos deben estar en el formato PEM que un servidor NGINX pueda 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 estén combinados en un solo archivo PFX. En ese caso, utilice OpenSSL para extraer los dos archivos.

  Consejo

  Los certificados SSL gratuitos están disponibles de proveedores como Let's Encrypt.

• Conectividad SSH.

Cuentas

Su Harmony debe tener un rol con permiso de Admin. (El permiso de Agent Install por sí solo no es suficiente.)

Recomendaciones

Al configurar su host de puerta de enlace API, debe seguir los puntos recomendados:

• No comparta el host con otras aplicaciones que no sean del sistema.

• Configure el host para un rendimiento óptimo.

• Instale los siguientes paquetes adicionales para su tipo de host:

  • Red Hat Enterprise Linux (RHEL): Si es basado en la nube, use un nodo de cómputo, con los siguientes grupos de paquetes:

    • Herramientas de depuración.
    • Utilidades de monitoreo de hardware.
    • Bibliotecas de compatibilidad.
    • Herramientas de desarrollo.
    • Herramientas de seguridad.

  • Debian, Ubuntu: Use una instalación predeterminada y seleccione los siguientes paquetes adicionales:

    • OpenSSH.

• Red: Abra el puerto 443 (HTTPS). Puede usar los siguientes comandos para hacerlo:

  Red Hat, Amazon LinuxDebian, Ubuntu

  firewall-cmd --zone=public --add-port=443/tcp --permanent
  firewall-cmd --reload
  

  ufw allow 443/tcp
  

Instalar y configurar un gateway API privado

Para instalar y configurar un gateway API privado, sigue estos pasos utilizando una cuenta con privilegios de root:

1. Descarga uno de los siguientes paquetes de software del gateway API privado desde la página del Portal Harmony Descargas, luego cópialo a tu host del gateway API:

   • Linux RPM: El archivo de paquete .rpm, para instalar en Red Hat o Amazon Linux.

   • Linux Debian: El archivo de paquete .deb, para instalar en Debian o Ubuntu Linux.

2. Ejecuta estos comandos para tu combinación de sistema operativo y versión del gateway, reemplazando x.x.x.x (.deb) o x.x.x-x (.rpm) con el número de versión descargado:

   Red Hat, Amazon LinuxDebian, UbuntuUbuntu 24.04 LTS

   Gateway API 10.61 o anteriorGateway API 10.62 o posterior

   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
   

   Gateway API 10.61 o anteriorGateway API 10.62 o posterior

   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
   

   Gateway API 11.38 o posterior

   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 la versión 11.49, el proceso de instalación agrega el siguiente archivo de configuración logrotate para los registros de NGINX:

   /etc/logrotate.d/nginx
   

   (Opcional) Abre este archivo, revisa la configuración y ajusta donde sea necesario.

4. Copia y renombra tus archivos de certificado utilizando los siguientes comandos:

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

1. Agrega los archivos de certificado al Java KeyStore de Jitterbit.

2. Ejecuta el siguiente comando y responde a las preguntas:

   jitterbit-api-gateway-config
   

   Consejo

   Para obtener ayuda sobre el comando jitterbit-api-gateway-config, ejecútalo con la opción --help.

   Notas importantes

   • La información que proporciones se almacena en el archivo /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml. En este archivo, tu nombre de usuario y contraseña de Harmony están encriptados, pero el nombre de usuario y la contraseña del servidor proxy están codificados en base64 solamente. Debes asegurarte de que este archivo tenga los permisos apropiados para evitar que otros usuarios lean estos valores.

   • La primera vez que configures un gateway API privado utilizando credenciales de Harmony, se crea automáticamente un nuevo usuario de gateway API separado con una contraseña que no expira en la organización con un rol de Administrador. Este usuario no está asociado con una dirección de correo electrónico, no puede iniciar sesión en el portal de Harmony y es solo para el gateway API. Las credenciales de este usuario se añaden al archivo gatewayconfig.yaml.

   • Desde la versión 11.32 del gateway API, si reconfiguras el gateway, se te hace la siguiente pregunta adicional:

     ¿Te gustaría generar nuevas credenciales de Gateway y sobrescribir las existentes? (y/N):
     

     Si respondes N, se utilizan las credenciales de usuario existentes. Si respondes Y, se crea un nuevo usuario.

   • Los usuarios del gateway API se muestran en la página de Gestión de Usuarios de la Consola de Administración en la forma <GatewayUser>_<orgID>_<ID>. Si el mismo usuario reconfigura el gateway en la misma organización, el nombre del usuario del gateway se le añade un guion bajo y un número incrementado, como _1.

   Ejemplo de salida

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

3. Ahora puedes acceder a las APIs de tu organización a través del gateway API privado.

   Nota

   Además de acceder a las APIs de la organización con tus URLs de API privadas, aún puedes usar las URLs de Jitterbit. Para bloquear el acceso a las URLs de Jitterbit, una operación puede confirmar primero que una URL proviene del gateway API privado y cancelar si no es así. El siguiente es un ejemplo de una prueba en la región NA (para las regiones EMEA y APAC, sustituye 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>
   

   Un inicio exitoso del gateway API privado se ve similar a lo siguiente:

   Ejemplo de inicio

   . . .
   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) Cambiar los protocolos y cifrados SSL soportados

Si es necesario, los protocolos y cifrados SSL soportados pueden ser cambiados en el archivo de configuración local /usr/local/openresty/nginx/conf/onpremise.conf utilizando las directivas ssl_protocols y ssl_ciphers respectivamente. Esto se puede hacer para eliminar el soporte para un protocolo o cifrado por defecto dependiendo de tus requisitos de seguridad. Por ejemplo:

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;

(Opcional) Cambiar el prefijo de URL de carga útil para soporte de ALB

Si se configura un entorno de múltiples gateways detrás de un balanceador de carga de aplicaciones (ALB) como AWS ALB, el protocolo utilizado para el enrutamiento de cargas útiles puede ser cambiado en el archivo /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml modificando la directiva payloadurlprefix. Por ejemplo:

payloadurlprefix: https://

Prueba el gateway de API privado

Para probar el gateway, sigue estos pasos:

1. Configura un API Manager API válido en la organización asociada con el gateway de API privado, y una URL de servicio API de API Manager en el formato https://JBExample123456.jitterbit.net/Development/1/customer.

2. Prueba la API. Si está funcionando correctamente, úsala para probar una URL de API privada reemplazando el dominio y subdominios de Jitterbit con los tuyos, manteniendo la misma ruta. (Si es una configuración de proxy, añade ?debug a la URL.)

   Ejemplo

   Si tu subdominio es mysubdomain y el dominio es example, la URL base se convierte en mysubdomain.example.com, y cambiarías la URL de servicio API https://JBExample123456.jitterbit.net/Development/1/customer a la URL de API privada https://mysubdomain.example.com/Development/1/customer. Para probar una URL de API privada de proxy https://mysubdomain.example.com/Development/1/customer, usa https://mysubdomain.example.com/Development/1/customer?debug. Si es exitoso, la salida es Proxy enabled: PROXY_URI, donde PROXY_URI es el valor proporcionado durante la configuración.

Autotest del gateway de API privado

Para ejecutar un autotest del gateway, usa la opción --test para el comando jitterbit-api-gateway-config. Después de un inicio de sesión exitoso, ejecuta automáticamente una serie de pruebas para asegurar una configuración adecuada. Estas incluyen importar un proyecto y API integrados, y llamar a la API a través del gateway. (Una URL de API debe estar disponible en tu suscripción para que el autotest sea exitoso.)

Actualizar un gateway API privado

Para actualizar un gateway API privado a una versión posterior, sigue estos pasos:

1. Descarga la última versión del software del gateway API privado a través de la página de Descargas. (Si es necesario, se pueden obtener versiones anteriores del software a través del soporte de Jitterbit.)

   Consejo

   Actualizar un gateway API privado a una versión posterior se puede hacer sin desinstalar la versión anterior del gateway, incluso al actualizar de una versión 10.x a una 11.x.

2. Crea una copia de seguridad del archivo de configuración del gateway API privado /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml.

3. Si hiciste cambios en los protocolos y cifrados SSL soportados, crea una copia de seguridad del archivo de configuración en las instalaciones /usr/local/openresty/nginx/conf/onpremise.conf.

4. Al actualizar desde una versión del gateway API privado 10.61 o anterior, crea una copia de seguridad de los archivos del certificado SSL. Los archivos del certificado SSL del gateway API privado se encuentran en estos directorios:

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

   Nota

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

5. Sigue los pasos de instalación. (Los comandos para actualizar un gateway API privado son los mismos que para la instalación.)

6. Copia la copia de seguridad del archivo de configuración del gateway API privado, el archivo de configuración en las instalaciones (si aplica) y los archivos del certificado SSL (si aplica) a la nueva instalación del gateway API privado.

7. (Opcional) Ejecuta jitterbit-api-gateway-config para realizar cambios de configuración adicionales. Puedes hacer esto si estás utilizando nuevas configuraciones que están disponibles en una versión posterior del gateway API privado.

8. Ejecuta este comando para reiniciar el gateway API privado:

   jitterbit-api-gateway-config -s restart
   

Desinstalar un gateway API privado

Para desinstalar un gateway API privado, ejecuta estos 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

El comando jitterbit-api-gateway-config te permite gestionar un gateway API privado de Jitterbit.

Sinopsis

jitterbit-api-gateway-config [OPTIONS]

Opciones

• -h, --help: Muestra un mensaje de ayuda y sale.

• -u USER, --user=USER: Nombre de usuario de Jitterbit Harmony.

• -p PASSWORD, --password=PASSWORD: Contraseña de Jitterbit Harmony.

• -o ORGANIZATION_ID, --organizationId=ORGANIZATION_ID: ID de organización de Jitterbit Harmony.

• -e ServiceUrl, --serviceUrl=ServiceUrl: URL de Servicios de Jitterbit.

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

  • start: Iniciar el gateway.

  • stop: Detener el gateway.

  • restart: Reiniciar el gateway.

• -d, --dns: Configurar interactivamente los servidores DNS.

• --proxyEnabled=true | false: Habilitar (true) o deshabilitar (false) un proxy.

• --proxyUri=PROXY_URI: URI del servidor proxy.

• --proxyUser=PROXY_USER: Nombre de usuario del servidor proxy.

• --proxyPassword=PROXY_PASSWORD: Contraseña del servidor proxy.

• -t, --test: Ejecutar pruebas automáticas.

• --debug: Habilitar salida de depuración para pruebas automáticas.

• --noColor: Deshabilitar colores de texto en la terminal.