Integración de EWS autohospedado

El dispositivo EWS se entrega como una imagen de Docker. Las siguientes secciones explican cómo configurar e implementar el dispositivo.

Configuración

El dispositivo espera que haya un archivo de configuración JSON. Esta sección explica el contenido del archivo. Consulta la sección Implementación para obtener instrucciones sobre cómo hacer que el archivo de configuración esté disponible para el dispositivo.

With OAuth 2.0

You can authenticate with client secret or with client certificate.

The token grant flow used is the client credentials flow.

With client secret

{
  "ews_endpoint": "https://outlook.office365.com/EWS/Exchange.asmx",
  "auth_type": "oauth2",
  "auth_oauth_authority": "https://login.microsoftonline.com/<tenant_id>/",
  "auth_oauth_client_id": "<client_id>",
  "auth_oauth_client_secret": "<client_secret>",
  "access_type": "impersonation",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

With client certificate

{
  "ews_endpoint": "https://outlook.office365.com/EWS/Exchange.asmx",
  "auth_type": "oauth2",
  "auth_oauth_authority": "https://login.microsoftonline.com/<tenant_id>/",
  "auth_oauth_client_id": "<client_id>",
  "auth_oauth_client_credential_private_key": "<private_key>",
  "auth_oauth_client_credential_thumbprint": "<thumbprint>",
  "access_type": "impersonation",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

With NTLM

{
  "host": "https://exchange-server.example.com",
  "port": 443,
  "auth_type": "ntlm",
  "auth_user": "[e-mail]",
  "access_type": "delegate",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

First, replace the dummy values in host, port, and auth_user with their real values, and change access_type if required. See the configuration reference for a description of these parameters and their allowed values.

Then, provide the service user password to the appliance as a REINFER_EWS_AUTH_PASS environment variable - see the Deployment section. The full list of environment variables that you can set to override values in the config is:

Nombre	Descripción
REINFER_EWS_AUTH_USER	Usuario del servidor de Exchange
REINFER_EWS_AUTH_PASS	Contraseña del servidor de Exchange
REINFER_EWS_ACCESS_TYPE	Tipo de acceso: "delegado" o "suplantación"
REINFER_EWS_HOST	Host del servidor de Exchange
REINFER_EWS_PORT	Puerto del servidor de Exchange

Mailbox configuration

You can specify one or more mailboxes in your configuration. For each mailbox, you have to provide the mailbox address and specify the following parameters:

Nombre	Descripción
bucket.owner	Proyecto del depósito en el que se debe sincronizar el buzón.
bucket.name	Nombre del depósito en el que se debe sincronizar el buzón.
start_from	Si se debe comenzar desde la última hora sincronizada ("depósito") o ignorar la última hora sincronizada y comenzar siempre desde start_timestamp ("config"). Debe establecerse en "depósito" para el funcionamiento normal, pero "config" puede ser útil en algunos casos al depurar.
start_timestamp	Marca de tiempo desde la que iniciar la sincronización del correo electrónico. Si no se establece, se sincronizarán todos los correos electrónicos.

La configuración utiliza los valores predeterminados para una serie de ajustes, como la frecuencia de sondeo o el tamaño del lote. Para personalizar aún más tu configuración, consulta la referencia de configuración.

Depósitos

La integración de Exchange sincroniza los datos de correo electrónico sin procesar en depósitos de Communications Mining. Al igual que otros recursos de Communications Mining, se crea un depósito en un proyecto que te permite controlar el acceso al depósito. Para leer desde un depósito, cargar en un depósito o gestionar depósitos, el usuario necesita los permisos respectivos en el proyecto en el que se encuentra el depósito.

Implementación

Puedes implementar el dispositivo EWS con Kubernetes o con Docker.

La implementación con Kubernetes te permite ejecutar varias instancias del dispositivo EWS, y cada instancia gestiona un subconjunto de buzones de correo que se sincronizarán.

Con Kubernetes

El uso de Kubernetes es una forma popular de ejecutar y gestionar aplicaciones en contenedores. Esta sección te muestra cómo implementar el dispositivo EWS utilizando Kubernetes. Se supone que tienes conocimientos básicos de Kubernetes y que tienes kubectl instalado. Consulta esta documentación si necesitas ayuda para empezar a utilizar Kubernetes.

Para implementar en Kubernetes, debes crear un archivo YAML que describa tu aplicación. Para empezar, copia el siguiente ejemplo.

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: reinfer-ews-appliance
  labels:
    app: reinfer-ews-appliance
spec:
  podManagementPolicy: Parallel
  replicas: 1
  selector:
    matchLabels:
      app: reinfer-ews-appliance
  serviceName: reinfer-ews-appliance
  template:
    metadata:
      labels:
        app: reinfer-ews-appliance
      name: reinfer-ews-appliance
    spec:
      containers:
        - args:
            - "reinfer-ews"
            - "--bind"
            - "0.0.0.0:8000"
            - "--reinfer-api-endpoint"
            - "https://<mydomain>.reinfer.io/api/"
            - "--shard-name"
            - "$(POD_NAME)"
            # This value should match `spec.replicas` above
            - "--total-shards"
            - "1"
          env:
            - name: REINFER_EWS_CONFIG
              value: "/mnt/config/example_ews_config"
            - name: REINFER_API_TOKEN
              valueFrom:
                secretKeyRef:
                  key: reinfer-api-token
                  name: reinfer-credentials
            - name: REINFER_EWS_AUTH_PASS
              valueFrom:
                secretKeyRef:
                  key: ews-auth-pass
                  name: reinfer-credentials
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
          image: "your.private.registry.com/reinfer/ews-appliance:TAG"
          name: reinfer-ews-appliance
          resources:
            requests:
              cpu: 0.05
              memory: 128Mi
          volumeMounts:
            - mountPath: /mnt/config
              name: config-vol
      volumes:
        - configMap:
            name: ews-config
            items:
              - key: example_ews_config
                path: example_ews_config
          name: config-vol

Antes de poder implementar el dispositivo utilizando este archivo YAML, hay que realizar algunos pasos adicionales.

En primer lugar, sustituye <mydomain>.reinfer.io por el punto de conexión de la API de tu tenant.

En segundo lugar, dado que nos gustaría evitar almacenar credenciales como texto no cifrado en nuestro archivo YAML, las variables de entorno REINFER_TOKEN y REINFER_EWS_AUTH_PASS se rellenan a partir de los secretos de Kubernetes. Crea los secretos así:

kubectl create secret generic reinfer-credentials \
  --from-literal=reinfer-api-token=<REINFER_TOKEN> \
  --from-literal=ews-auth-pass=<MSEXCHANGE_PASSWORD>

Por último, como nos gustaría cargar la configuración del dispositivo desde un archivo local, debemos montar ese archivo en el pod. Para ello, almacenamos los datos en un ConfigMap de Kubernetes y montamos el ConfigMap como un volumen. Crea el ConfigMap así:

kubectl create configmap ews-config \
  --from-file=example_ews_config=your-ews-config.json

Nota:

Nota

Como alternativa al almacenamiento local del archivo de configuración, puedes cargarlo en Communications Mining y dejar que el dispositivo EWS lo obtenga a través de la API de Communications Mining. Esto se describe aquí. Si se especifican los archivos de configuración locales y remotos, el dispositivo utilizará el archivo de configuración local.

Ahora puedes crear tu statefulset y comprobar que todo se está ejecutando:

kubectl apply -f reinfer-ews.yaml
kubectl get sts

Con Docker

Como alternativa, puedes ejecutar el dispositivo EWS en Docker. El siguiente comando iniciará el dispositivo con los mismos parámetros que se utilizan en la sección Kubernetes .

EWS_CONFIG_DIR=
REINFER_API_TOKEN=
MSEXCHANGE_PASSWORD=
TAG=

sudo docker run \
-v $EWS_CONFIG_DIR:/mnt/config \
--env REINFER_EWS_CONFIG=/mnt/config/your_ews_config.json \
--env REINFER_API_TOKEN=$REINFER_API_TOKEN \
--env REINFER_EWS_AUTH_PASS=$MSEXCHANGE_PASSWORD \
eu.gcr.io/reinfer-gcr/ews:$TAG \
reinfer-ews --reinfer-api-endpoint https://<mydomain>.reinfer.io/api/ &> ews_$(date -Iseconds).log

• Sustituye <mydomain>.reinfer.io por el punto de conexión de la API de tu tenant.
• Sustituye your_ews_config.json por el nombre de tu archivo JSON de configuración de EWS.

El dispositivo se ejecutará continuamente sincronizando correos electrónicos en la plataforma Communications Mining. Si se detiene y se vuelve a iniciar, se reanudará desde el último estado de sincronización del depósito almacenado.

Con Docker (almacenamiento local)

El dispositivo EWS puede guardar los correos electrónicos extraídos localmente en lugar de enviarlos a la plataforma Communications Mining.

EWS_LOCAL_DIR=
MSEXCHANGE_PASSWORD=
CONFIG_OWNER=
CONFIG_KEY=
TAG=

sudo docker run \
-v $EWS_LOCAL_DIR:/mnt/ews \
--env REINFER_EWS_AUTH_PASS=$MSEXCHANGE_PASSWORD \
eu.gcr.io/reinfer-gcr/ews:$TAG \
reinfer-ews --local-files-prefix /mnt/ews \
--remote-config-owner $CONFIG_OWNER --remote-config-key $CONFIG_KEY &> ews_$(date -Iseconds).log

• El dispositivo espera encontrar la configuración en $EWS_LOCAL_DIR/config/$CONFIG_OWNER/$CONFIG_KEY.json. También puedes proporcionar la ruta a la configuración estableciendo la variable de entorno $REINFER_EWS_CONFIG .
• El dispositivo guardará el estado de sincronización en $EWS_LOCAL_DIR/state. Si se detiene y se vuelve a iniciar, se reanudará desde el último estado de sincronización almacenado.
• El dispositivo guardará los datos en $EWS_LOCAL_DIR/data.

Almacenar la configuración en Communications Mining

En lugar de proporcionar un archivo de configuración local al dispositivo como lo hacías si seguías la guía de implementación del dispositivo EWS, puedes gestionar el archivo de configuración en Communications Mining. Ten en cuenta que si se especifican los archivos de configuración locales y remotos, el dispositivo utilizará de forma predeterminada el archivo de configuración local.

Primero, sube tu archivo de configuración JSON a Communications Mining:

curl -H "Authorization: Bearer $REINFER_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F 'file=@your-ews-config.json' \
  -XPUT https://<mydomain>.reinfer.io/api/v1/appliance-configs/<project-name>/<config-name>

Para ver la configuración actual:

curl -H "Authorization: Bearer $REINFER_TOKEN" \
  -XGET https://<mydomain>.reinfer.io/api/v1/appliance-configs/<project-name>/<config-name>

A continuación, en el archivo YAML de Kubernetes, establece el parámetro --remote-config-owner en el nombre del proyecto y el parámetro --remote-config-key en el nombre de la configuración.

Referencia

Parámetros de la aplicación

Consulta la siguiente tabla para ver una lista de los parámetros de aplicación disponibles. Puedes obtener más información sobre la ejecución del dispositivo EWS aquí.

Parámetro	Descripción
--reinfer-api-endpoint	Punto final para conectarse a la API Reinferir. Mutuamente excluyente con --local-files-prefix.
--local-files-prefix	Ruta para almacenar los correos electrónicos sincronizados y el estado de sincronización del depósito. Mutuamente excluyente con --reinfer-api-endpoint y REINFER_API_TOKEN.
--remote-config-owner	Proyecto propietario del archivo de configuración del dispositivo EWS remoto.
--remote-config-key	Nombre del archivo de configuración del dispositivo EWS remoto.
--debug-level	Nivel de depuración. 0 = Sin depuración, 1 = Depuración de servicio, 2 = Depuración completa. Predeterminado: 1.
--shard-name	Nombre del fragmento, es decir, ews-N del que extraer el número del fragmento. Cuando se ejecuta en Kubernetes, puedes establecerlo en el nombre del pod.
--total-shards	El número total de instancias en el clúster de dispositivos. Cuando se ejecuta en Kubernetes, debe establecerse en el mismo valor que el número de instancias en StatefulSet.
--restart-on-unrecoverable-errors	Si se habilita, los fallos irrecuperables darán lugar a que todo el servicio se reinicie sin bloquearse.

Parámetros de configuración

Consulta la siguiente tabla para ver una lista de los parámetros de configuración disponibles. Puedes obtener más información sobre cómo escribir el archivo de configuración del dispositivo EWS aquí.

Nombre	Descripción
host	Host del servidor de Exchange. Puede ser anulado por la variable de entorno REINFER_EWS_HOST .
port	Puerto del servidor de Exchange. Valor predeterminado: 80. Puede ser anulado por la variable de entorno REINFER_EWS_PORT .
auth_type	Solo se permite "ntlm".
auth_user	Usuario del servidor de Exchange. Puede ser anulado por la variable de entorno REINFER_EWS_AUTH_USER .
auth_password	Contraseña del servidor de Exchange. Puede ser anulado por la variable de entorno REINFER_EWS_AUTH_PASS .
access_type	Tipo de acceso: "delegado" o "suplantación". Predeterminado: "delegado". Puede ser anulado por la variable de entorno REINFER_EWS_ACCESS_TYPE .
ews_ssl_verify	Si se establece en "falso", no se verificarán los certificados. Predeterminado: "verdadero".
poll_frequency	Cuánto tiempo esperar entre lotes, en segundos. Predeterminado: 15.
poll_message_sleep	Cuánto tiempo esperar entre correos electrónicos individuales en un lote, en segundos. Predeterminado: 0.1.
max_concurrent_uploads	Número de cargas simultáneas en Communications Mining, entre 0 y 32. Predeterminado: 8.
emails_per_folder	Número máximo de correos electrónicos para recuperar de cada carpeta por lote, entre 1 y 100 000. Predeterminado: 2520. Esta configuración permite que el dispositivo progrese en todas las carpetas de manera uniforme en caso de que haya una carpeta muy grande.
reinfer_batch_size	Cuántos correos electrónicos recuperar por lote, entre 1 y 1000. Predeterminado: 80.
mailboxes	Lista de buzones de correo a recuperar. Consulta aquí para obtener una explicación de cómo configurar los buzones de correo.
audit_email	Si ha configurado el dispositivo con una configuración remota, Communications Mining enviará un correo electrónico a esta dirección cada vez que se actualice la configuración. Predeterminado: Ninguno.
ews_ssl_ciphers	Hacer que el dispositivo EWS utilice cifrados específicos. Los cifrados deben ser una cadena en el formato de lista de cifrado OpenSSL. Predeterminado: Ninguno.