Intégration EWS auto-hébergée

L'appli EWS est livrée sous forme d'image Docker. Les sections ci-dessous expliquent comment configurer et déployer l'appliance.

Configuration

L'appli s'attend à ce qu'un fichier de configuration JSON soit présent. Cette section explique le contenu du fichier. Reportez-vous à la section Déploiement (Deployment) pour savoir comment mettre le fichier de configuration à la disposition de l'appli.

Avec OAuth 2.0

Vous pouvez vous authentifier avec la clé secrète du client ou avec le certificat client.

Le flux d'octroi de jetons utilisé est le flux d'informations d'identification client.

Avec clé secrète de client

{
  "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"
    }
  }
}

Avec certificat client

{
  "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"
    }
  }
}

Avec 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"
    }
  }
}

Tout d'abord, remplacez les valeurs factices dans host, port et auth_user par leurs valeurs réelles et modifiez access_type si nécessaire. Consultez la référence de configuration pour obtenir une description de ces paramètres et de leurs valeurs autorisées.

Ensuite, fournissez le mot de passe de l'utilisateur de service à l'appareil en tant que variable d'environnement REINFER_EWS_AUTH_PASS - voir la section Déploiement (Deployment). La liste complète des variables d'environnement que vous pouvez définir pour remplacer les valeurs dans la configuration est :

Nom	DESCRIPTION
REINFER_EWS_AUTH_USER	Utilisateur du serveur Exchange
REINFER_EWS_AUTH_PASS	Mot de passe du serveur Exchange
REINFER_EWS_ACCESS_TYPE	Type d'accès : « délégué » ou « emprunt d'identité »
REINFER_EWS_HOST	Hôte du serveur Exchange
REINFER_EWS_PORT	Port du serveur Exchange

Configuration de la boîte aux lettres

Vous pouvez spécifier une ou plusieurs boîtes aux lettres dans votre configuration. Pour chaque boîte aux lettres, vous devez fournir l'adresse de la boîte aux lettres et spécifier les paramètres suivants :

Nom	DESCRIPTION
bucket.owner	Projet du compartiment dans lequel la boîte aux lettres doit être synchronisée.
bucket.name	Nom du compartiment dans lequel la boîte aux lettres doit être synchronisée.
start_from	S'il faut démarrer à partir de la dernière heure synchronisée ("compartiment") ou ignorer la dernière heure synchronisée et toujours démarrer à partir de start_timestamp ("config"). Doit être défini sur "compartiment" pour un fonctionnement normal, mais "config" peut être utile dans certains cas lors du débogage.
start_timestamp	Horodatage à partir duquel démarrer la synchronisation des e-mails. Si ceci n’est pas défini, tous les e-mails seront synchronisés.

La configuration utilise les valeurs par défaut pour un certain nombre de paramètres tels que la fréquence d'interrogation ou la taille des lots. Pour personnaliser davantage votre configuration, reportez-vous à la référence de configuration.

Compartiments

L'intégration Exchange synchronise les données de messagerie brutes dans les compartiments Communications Mining. Comme pour les autres ressources Communications Mining, un compartiment est créé dans un projet qui vous permet de contrôler l'accès au compartiment. Pour lire à partir d’un compartiment, télécharger dans un compartiment ou gérer des compartiments, l’utilisateur a besoin des autorisations respectives dans le projet dans lequel se trouve le compartiment.

Déploiement

Vous pouvez déployer l'appli EWS avec Kubernetes ou avec Docker.

Le déploiement avec Kubernetes vous permet d'exécuter plusieurs instances de l'appli EWS, chaque instance gérant un sous-ensemble de boîtes aux lettres à synchroniser.

Avec Kubernetes

L'utilisation de Kubernetes est un moyen populaire d'exécuter et de gérer des applications conteneurisées. Cette section vous montre comment déployer l'appli EWS à l'aide de Kubernetes. Il suppose que vous avez une familiarité de base avec Kubernetes et que kubectl est installé. Veuillez consulter cette documentation si vous avez besoin d’aide pour démarrer avec Kubernetes.

Pour déployer sur Kubernetes, vous devez créer un fichier YAML décrivant votre application. Pour commencer, copiez l'exemple ci-dessous.

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

Avant de pouvoir déployer l'appli à l'aide de ce fichier YAML, vous devez effectuer quelques étapes supplémentaires.

Tout d'abord, remplacez <mydomain>.reinfer.io par votre point de terminaison d'API de locataire.

Deuxièmement, comme nous voulons éviter de stocker les informations d'identification sous forme de texte clair dans notre fichier YAML, les variables d'environnement REINFER_TOKEN et REINFER_EWS_AUTH_PASS sont renseignées à partir des clés secrètes Kubernetes. Créez les clés secrètes comme suit :

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

Enfin, puisque nous souhaitons charger la configuration de l'appareil à partir d'un fichier local, nous devons monter ce fichier dans le pod. Pour ce faire , stockez les données dans une ConfigMap Kubernetes et montez la ConfigMap en tant que volume. Créez la ConfigMap comme suit :

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

Remarque :

Comme alternative au stockage local du fichier de configuration, vous pouvez le télécharger sur Communications Mining et laisser l'appli EWS le récupérer via l'API Communications Mining. Ceci est décrit ici. Si les fichiers de configuration locaux et distants sont spécifiés, l'appareil utilisera le fichier de configuration local.

Vous pouvez maintenant créer votre ensemble d'états et vérifier que tout est en cours d'exécution :

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

Avec Docker

Vous pouvez également exécuter l'appli EWS dans Docker. La commande ci-dessous démarrera l'appli avec les mêmes paramètres que ceux utilisés dans la section Kubernetes .

EWS_CONFIG_DIR=
REINFER_API_TOKEN=
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 \
  eu.gcr.io/reinfer-gcr/ews:$TAG \
  --reinfer-api-endpoint https://<mydomain>.reinfer.io/api/ \
  &> ews_$(date -Iseconds).log

• Remplacez <mydomain>.reinfer.io par votre point de terminaison d'API de locataire.
• Remplacez your_ews_config.json par le nom de votre fichier JSON de configuration EWS.

L'appareil exécutera une synchronisation continue des e-mails dans la plate-forme Communications Mining. S'il est arrêté et redémarré, il récupère à partir du dernier état de synchronisation du compartiment stocké.

Avec Docker (stockage local)

L'appli EWS peut enregistrer les e-mails extraits localement au lieu de les transmettre à la plate-forme Communications Mining.

EWS_LOCAL_DIR=
CONFIG_OWNER=
CONFIG_KEY=
TAG=

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

• L'appareil s'attend à trouver la configuration dans $EWS_LOCAL_DIR/config/$CONFIG_OWNER/$CONFIG_KEY.json. Vous pouvez également fournir le chemin d'accès à la configuration en définissant la variable d'environnement $REINFER_EWS_CONFIG comme indiqué dans l'exemple précédent.
• L'appareil enregistrera l'état de synchronisation dans $EWS_LOCAL_DIR/state. S'il est arrêté et redémarré, il reprendra à partir du dernier état de synchronisation enregistré.
• L'appareil enregistrera les données dans $EWS_LOCAL_DIR/data.

Avec Docker (Stockage Blob Azure)

L'appareil EWS peut enregistrer les e-mails extraits dans le Stockage Blob Azure au lieu de les transmettre à la plate-forme Communications Mining.

EWS_CONFIG_DIR=
AZ_STORAGE_ACCOUNT_NAME=
AZ_CONTAINER_NAME=
TAG=

sudo docker run \
  -v $EWS_CONFIG_DIR:/mnt/config \
  --env REINFER_EWS_CONFIG=/mnt/config/your_ews_config.json \
  eu.gcr.io/reinfer-gcr/ews:$TAG \
  --private-file-prefix az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME \
  &> ews_$(date -Iseconds).log

• Vous devez fournir le chemin d'accès à la configuration en définissant la variable d'environnement $REINFER_EWS_CONFIG .

• L'appareil s'authentifie auprès de Stockage Blob Azure à l'aide de l'une des méthodes DefaultAzureCredential. Veuillez utiliser une méthode qui vous convient. Quelle que soit la méthode que vous utilisez, accordez le rôle « Contributeur de données blob de stockage » (Storage Blob Data Contributor) à l'appareil.

• L'appareil enregistrera l'état de synchronisation dans az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/state. S'il est arrêté et redémarré, il reprendra à partir du dernier état de synchronisation enregistré.
• L'appareil enregistrera les données dans az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/data.

Configuration du magasin dans Communications Mining

Au lieu de fournir un fichier de configuration local à l'appliance comme vous le faisiez si vous aviez suivi le guide de déploiement de l'appliance EWS, vous pouvez à la place gérer le fichier de configuration dans Communications Mining. Notez que si les fichiers de configuration locaux et distants sont spécifiés, l'appareil utilisera par défaut le fichier de configuration local.

Tout d'abord, téléchargez votre fichier de configuration JSON dans 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>

Pour voir la configuration actuelle :

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

Ensuite, dans le fichier YAML kubernetes, définissez le paramètre --remote-config-owner sur le nom du projet et le paramètre --remote-config-key sur le nom de la configuration.

Référence (Reference)

Paramètres d’application

Consultez le tableau ci-dessous pour obtenir une liste des paramètres d’application disponibles. Vous pouvez en savoir plus sur l'exécution de l'appli EWS ici.

Paramètre	DESCRIPTION
--reinfer-api-endpoint	Point de terminaison pour se connecter à l'API Reinfer. mutuellement exclusif avec --local-files-prefix.
--local-files-prefix	Chemin d'accès pour stocker les e-mails synchronisés et l'état de synchronisation du compartiment. Listé mutuellement exclusif avec --reinfer-api-endpoint et REINFER_API_TOKEN.
--remote-config-owner	Projet qui possède le fichier de configuration de l'appli EWS distante.
--remote-config-key	Nom du fichier de configuration de l'appli EWS distante.
--debug-level	Niveau de débogage. 0 = Pas de débogage, 1 = Débogage du service, 2 = Débogage complet. Par défaut : 1.
--shard-name	Nom de la partition, c'est-à-dire ews-N pour extraire le numéro de la partition. Lors de l'exécution dans Kubernetes, vous pouvez le définir sur le nom du pod.
--total-shards	Le nombre total d'instances dans le cluster d'appareils. Lors de l'exécution dans Kubernetes, doit être défini sur la même valeur que le nombre d'instances dans l'ensemble d'états.
--restart-on-unrecoverable-errors	Si cette option est activée, les défaillances irrécupérables entraîneront le redémarrage de l’ensemble du service sans planter.

Paramètres de configuration

Consultez le tableau ci-dessous pour découvrir une liste des paramètres de configuration disponibles. Vous pouvez en savoir plus sur l'écriture du fichier de configuration de l'appli EWS ici.

Nom	DESCRIPTION
host	Hôte du serveur Exchange. Peut être remplacée par la variable d'environnement REINFER_EWS_HOST .
port	Port du serveur Exchange. Par défaut : 80. Peut être remplacée par la variable d'environnement REINFER_EWS_PORT .
auth_type	Seul « ntlm » autorisé.
auth_user	Utilisateur du serveur Exchange. Peut être remplacée par la variable d'environnement REINFER_EWS_AUTH_USER .
auth_password	Mot de passe du serveur Exchange. Peut être remplacée par la variable d'environnement REINFER_EWS_AUTH_PASS .
access_type	Type d'accès : "délégué" ou "emprunt d'identité". Par défaut : "delegate". Peut être remplacée par la variable d'environnement REINFER_EWS_ACCESS_TYPE .
ews_ssl_verify	Si défini sur « false », ne vérifie pas les certificats. Par défaut : "true".
poll_frequency	Le temps d’attente entre les lots, en secondes. Par défaut : 15.
poll_message_sleep	La durée d'attente entre les e-mails individuels d'un lot, en secondes. Par défaut : 0,1.
max_concurrent_uploads	Nombre de téléchargements simultanés vers Communications Mining, entre 0 et 32. Par défaut : 8.
emails_per_folder	Nombre maximum d'e-mails à récupérer dans chaque dossier par lot, entre 1 et 100 000. Par défaut : 2 520. Ce paramètre permet à l'appli de faire des progrès sur tous les dossiers de manière égale au cas où il y aurait un dossier très volumineux.
reinfer_batch_size	Nombre d'e-mails à récupérer par lot, entre 1 et 1 000. Par défaut : 80.
mailboxes	Liste des boîtes aux lettres à récupérer. Voir ici pour une explication sur la configuration des boîtes aux lettres.
audit_email	Si vous avez configuré l'appareil avec une configuration à distance, Communications Mining enverra un e-mail à cette adresse chaque fois que la configuration sera mise à jour. Par défaut : Aucun.
ews_ssl_ciphers	Rendre l'appli EWS utiliser des chiffrements spécifiques. Les chiffrements doivent être une chaîne au format de liste de chiffrement OpenSSL. Par défaut : Aucun.