Instalar una puerta de enlace API privada de Jitterbit en Linux

Descripción general

Esta página explica cómo instalar, configurar y probar una puerta de enlace API privada.

Requisitos del sistema

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

Hardware

Sistemas operativos

Red

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

  A partir de la versión 12.13 de la puerta de enlace API privada, el nombre de dominio puede contener caracteres multibyte. El comando jitterbit-api-gateway-config convierte el nombre de dominio a Punycode para la validación de DNS y la autoprueba, así que registra la forma Punycode del nombre de dominio en tu DNS o archivo de hosts. Solicita también el certificado SSL para la forma Punycode.

• Un certificado SSL válido para el subdominio, de una autoridad de certificación reconocida; no utilices un certificado autofirmado.

  El certificado debe constar de dos archivos: un archivo CRT (.crt) para el certificado firmado, y KEY (.key) para la clave privada. Estos deben estar en formato PEM que un servidor NGINX pueda entender. (A veces la extensión de los archivos es diferente; frecuentemente las extensiones CRT, PEM y CER son intercambiables.) También es posible que los dos archivos se combinen en un único archivo PFX. En ese caso, usa OpenSSL para extraer los dos archivos.

  Consejo

  Hay certificados SSL gratuitos disponibles de proveedores como Let's Encrypt.

• Conectividad SSH.

Cuentas

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

Recomendaciones

Al configurar tu host de puerta de enlace API, debes seguir los puntos recomendados:

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

• Configura el host para un rendimiento óptimo.

• Instala los siguientes paquetes adicionales para tu tipo de host:

  • Red Hat Enterprise Linux (RHEL): Si está basado en la nube, usa un nodo de Compute, 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: Usa una instalación predeterminada y selecciona los siguientes paquetes adicionales:

    • OpenSSH.

• Red: Abre el puerto 443 (HTTPS). Puedes 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 una puerta de enlace API privada

Para instalar y configurar una puerta de enlace API privada, sigue estos pasos usando una cuenta con privilegios de root:

1. Descarga uno de los siguientes paquetes de software de puerta de enlace API privada desde la página Descargas del Portal Harmony y cópialo a tu host de puerta de enlace 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 de puerta de enlace, 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

   Puerta de enlace API 10.61 o anteriorPuerta de enlace 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
   

   Puerta de enlace API 10.61 o anteriorPuerta de enlace 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
   

   Puerta de enlace 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. A partir de la versión 11.49, el proceso de instalación añade el siguiente archivo de configuración de 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 cambia el nombre de tus archivos de certificado usando los siguientes comandos:

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

5. Añade los archivos de certificado al Almacén de claves Java de Jitterbit.

6. 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 se cifran, pero el nombre de usuario y la contraseña del servidor proxy se codifican únicamente en base64. Debes asegurar que este archivo tenga los permisos apropiados para evitar que otros usuarios lean estos valores.

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

   • A partir de la versión 11.32 de puerta de enlace API, si reconfigutas la puerta de enlace, se te hace la siguiente pregunta adicional:

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

     Si respondes N, se usan las credenciales del usuario existente. Si respondes Y, se crea un nuevo usuario.

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

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

1. Ahora puedes acceder a las APIs de tu organización a través de la puerta de enlace de API privada.

   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 de la puerta de enlace de API privada 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 de la puerta de enlace de API privada se ve similar al 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 SSL y cifrados compatibles

Si es necesario, los protocolos SSL y cifrados compatibles se pueden cambiar 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 de un protocolo o cifrado predeterminado según 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 los niveles máximos de subdominio compatibles para un FQDN personalizado

El nombre de dominio completamente calificado (FQDN) personalizado de una puerta de enlace de API privada puede contener múltiples niveles de subdominio, como mysubdomain.department.region.example.com. Desde la versión 12.9 de la puerta de enlace de API privada, una puerta de enlace de API privada admite FQDNs con hasta 10 niveles de subdominio de forma predeterminada. La clave MaxDomainParts no está presente en gatewayconfig.yaml de forma predeterminada.

Si tu FQDN personalizado requiere más de 10 niveles de subdominio, agrega manualmente la clave MaxDomainParts al archivo con la cantidad de niveles que necesites. Por ejemplo:

MaxDomainParts: 15

Después de actualizar gatewayconfig.yaml, ejecuta jitterbit-api-gateway-config para aplicar el cambio.

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

Si estás configurando un entorno de múltiples puertas de enlace detrás de un equilibrador de carga de aplicaciones (ALB) como AWS ALB, el protocolo utilizado para el enrutamiento de carga útil se puede cambiar en el archivo /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml modificando la directiva payloadurlprefix. Por ejemplo:

payloadurlprefix: https://

Probar la puerta de enlace de API privada

Para probar la puerta de enlace, sigue estos pasos:

1. Configura una API de API Manager válida en la organización asociada con la puerta de enlace de API privada, y una URL de servicio de API de API Manager en el formato https://JBExample123456.jitterbit.net/Development/1/customer.

2. Prueba la API. Si funciona correctamente, úsala para probar una URL de API privada reemplazando el dominio y subdominios de Jitterbit con los tuyos, conservando la misma ruta. (Si es una configuración de proxy, agrega ?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 de 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 tiene éxito, la salida es Proxy enabled: PROXY_URI, donde PROXY_URI es el valor proporcionado durante la configuración.

Autoprueba de puerta de enlace privada de API

Para ejecutar una autoprueba de puerta de enlace, usa la opción --test del comando jitterbit-api-gateway-config. Después de un inicio de sesión exitoso, se ejecuta automáticamente una serie de pruebas para garantizar la configuración adecuada. Estas incluyen importar un proyecto y una API integrados, e invocar la API a través de la puerta de enlace. (Debe haber una URL de API disponible en tu suscripción para que la autoprueba sea exitosa.)

Actualizar una puerta de enlace privada de API

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

1. Descarga la versión más reciente del software de puerta de enlace privada de API en la página Descargas. (Si es necesario, versiones anteriores del software se pueden obtener del Soporte de Jitterbit.)

   Consejo

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

2. Crea una copia de seguridad del archivo de configuración de la puerta de enlace privada de API /usr/local/openresty/nginx/conf/onpremise/gatewayconfig.yaml.

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

4. Al actualizar desde una versión de puerta de enlace privada de API 10.61 o anterior, crea una copia de seguridad de los archivos de certificado SSL. Los archivos de certificado SSL de la puerta de enlace privada de API 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 privada de API, no es necesario hacer una copia de seguridad ni copiar los archivos de certificado SSL. Estos archivos se conservan durante una actualización.

5. Sigue los pasos de instalación. (Los comandos para actualizar una puerta de enlace privada de API son los mismos que para la instalación.)

6. Copia la copia de seguridad del archivo de configuración de la puerta de enlace privada de API, el archivo de configuración local (si aplica) y los archivos de certificado SSL (si aplica) a la nueva instalación de la puerta de enlace privada de API.

7. (Opcional) Ejecuta jitterbit-api-gateway-config para realizar cambios de configuración adicionales. Puedes hacerlo si usas nuevas opciones de configuración que están disponibles en una versión posterior de la puerta de enlace privada de API.

8. Ejecuta este comando para reiniciar la puerta de enlace privada de API:

   jitterbit-api-gateway-config -s restart
   

Desinstalar una puerta de enlace privada de API

Para desinstalar una puerta de enlace privada de API, 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 administrar una puerta de enlace privada de API 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 Jitterbit Services.

• -s COMMAND, --server=COMMAND: Los valores válidos para COMMAND son:

  • start: Inicia la puerta de enlace.

  • stop: Detiene la puerta de enlace.

  • restart: Reinicia la puerta de enlace.

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

• --proxyEnabled=true | false: Habilita (true) o deshabilita (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: Desactivar colores de texto en la terminal.