Верхнеуровневое описание архитектуры Системы и требования к инфраструктуре
Система состоит из двух логических элементов:
- Платформа, анализирующая данные (далее — Платформа). Устанавливается в закрытом периметре Компании, без доступа к сети Интернет.
- EWS-коннектор — программное обеспечение, используемое в качестве промежуточного звена между почтовым сервером MS Exchange и Платформой. Функциональные возможности EWS-Коннектора сводятся к получению данных по EWS-протоколу (443/TCP) с почтового сервера MS Exchange и транзиту их по защищенному протоколу HTTPS в платформу. Коннектор устанавливается на сервер под управлением Windows и представляет собой службу MS Windows.
Принципиальная схема сетевого взаимодействия.
Для автоматизации загрузки пользователей в платформу может использоваться AD-коннектор.
AD-коннектор
AD-коннектор подключается к серверу Active Directory по протоколу LDAP, получает список пользователей AD и загружает его в платформу через HTTPS / 443 через Public Yva Api.
Поля, получаемые из AD:
- objectGUID
- givenName
- sn
- displayName
- title
- department
- manager
- (&(samAccountType=805306368)(mail=*))
EWS-коннектор
EWS-коннектор подключается к серверу MS Exchange по протоколу EWS и отправляет сообщения из почтовых ящиков на сервере Api (3), через соединение 2-3 (HTTPS / 443).
Коннектор Microsoft Exchange Yva.ai не выполняет изменение данных в Microsoft Exchange. Это гарантируется тем фактом, что коннектор использует только методы чтения данных в Exchange Web Services Managed API, и запросы выполняются от имени пользователя с ограниченными правами
Поля, получаемые с сервера MS Exchange:
- subject
- body
- Headers:
- Реальный отправитель письма(Sender)
- Email отправителя письма(From)
- Email-ы получателей письма
- Email-ы вторичных получателей письма (CC)
- Email-ы скрытых получателей письма(BCC)
- Признак письма, отправленного пользователем (IsSent)
- Время отправки
- Время получения
- IsFlagged, IsAutomatic и Importance (признаки есть не во всех конфигурациях серверов, получаем у кого это возможно)
Коннектор EWS для получения писем использует стандартную библиотеку от Microsoft в следующем виде:
/// <summary>
/// Unique message id.
/// This property can be null if there is no suitable in external system.
/// </summary>
public string Id { get; set; }
/// <summary>
/// Date the message was sent.
/// </summary>
public DateTime SentAt { get; set; }
/// <summary>
/// Date the message was received.
/// </summary>
public DateTime? ReceivedAt { get; set; }
/// <summary>
/// The from address for this e-mail message.
/// </summary>
public MailAddress From { get; set; }
/// <summary>
/// Collection that contains the recipients of this e-mail message.
/// This property can be null or empty collection.
/// </summary>
public List<MailAddress> To { get; set; }
/// <summary>
/// Collection that contains the carbon copy (CC) recipients for this e-mail message.
/// This property can be null or empty collection.
/// </summary>
public List<MailAddress> Cc { get; set; }
/// <summary>
/// Collection that contains the blind carbon copy (BCC) recipients for this e-mail message.
/// This property can be null or empty collection.
/// </summary>
public List<MailAddress> Bcc { get; set; }
/// <summary>
/// The priority of this e-mail message.
/// This property can be null.
/// </summary>
public MailImportance? Importance { get; set; }
/// <summary>
/// Thread id.
/// This property can be null or empty string.
/// </summary>
public string ThreadId { get; set; }
/// <summary>
/// The subject line for this e-mail message.
/// This property can be null or empty string.
/// </summary>
public string Subject { get; set; }
/// <summary>
/// The body of the message. It can be in HTML or text format.
/// </summary>
public MailBody Body { get; set; }
/// <summary>
/// Message headers.
/// This property can be null or empty collection.
/// </summary>
public List<MailHeader> Headers { get; set; }
/// <summary>
/// Is this message flagged, starred, marked, etc?
/// This property should be set only if external source has exact information.
/// </summary>
public bool? IsFlagged { get; set; }
/// <summary>
/// Is this message was sent by the owner or received?
/// </summary>
public bool IsSent { get; set; }
/// <summary>
/// Is Automatic mail?
/// </summary>
public bool? IsAutomatic { get; set; }
Возможности ограничения EWS-коннектора со стороны инфраструктуры:
- Ограничение возможностей сервисной учетной записи, с правами которой EWS-коннектор подключается к Exchange-серверу средствами администрирования Throttlingpolicy https://docs.microsoft.com/en-us/powershell/module/exchange/server-health-and-performance/new-throttlingpolicy?view=exchange-ps
- Снижение приоритета получения доступа к данных сервисной учетной записи, с привилегиями которой EWS-коннектор подключается к Exchange серверу
EWS-коннектор спроектирован таким образом, что работает в асинхронном режиме, получая данные порциями по 10 сообщений за одно обращение и делая паузу между обращениями на передачу данных в платформу. Пауза зависит от объемов полученных объектов и составляет от 3 до 15 секунд.
Коннектор корректно обрабатывает исключения почтового сервера, предписывающие временно приостановить отправку запросов.
Коннектор оперирует белым списком пользователей, запрашивая данные только о почтовых ящиках, указанных в нем.
Есть возможность управления уровнем логгирования приложения, изменяя значение переменной nlog.rules.logger[writeTo=file] в файле nlog.config.
Возможные значения: Trace, Debug, Info, Warn, Error и Fatal.
Файлы конфигурации коннекторов
- ConnectorService.exe.config
Общие настройки коннектора:
Поле |
Описание |
|
1 |
SyncRepeatPeriodInMin |
Интервал через который коннектор будет начинать работу. |
2 |
IgnoreTrustForSSL |
Не проверять SSL-сертификат ADFS\Exchange сервера. |
3 |
ConnectAdfs |
Признак необходимости подключения ADFS (пользователи). Требует заполнения конфигурации подключения к ADFS (см. ниже). |
4 |
ConnectExchange |
Признак необходимости подключения Exchange (письма). Требует заполнения конфигурации подключения к Exchange (см. ниже). |
5 |
SendToYva |
Признак необходимости отправки результатов работы коннектора в Yva. Требует заполнения конфигурации подключения к Yva (см. ниже). |
6 |
DataPath |
Путь в директорию в которую будут записаны результаты работы коннектора. Используется при SendToYva = false. |
Поля, использующиеся при указании значения True параметра ConnectAdfs
Поле |
Описание |
|
1 |
AdfsLdapUrl |
URL вида LDAP://dc.domain.com |
2 |
AdfsUserLogin |
Логин (еmail) пользователя, от имени которого коннектор будет работать с ADFS. |
3 |
AdfsUserPassword |
Пароль пользователя, от имени которого коннектор будет работать с ADFS. |
4 |
AdfsItemsPerPage |
Количество сообщений, получаемых за один запрос к серверу |
Поля, использующиеся при `ConnectExchange = true`.
Поле |
Описание |
|
1 |
ExchangeUrl |
Exchange Web Services (EWS) URL. ("https://dc.domain.com/EWS/Exchange.asmx") |
2 |
ExchangeVersion |
Поддерживаемые версии: Exchange2010, Exchange2010_SP1, Exchange2013. Exchange2013 по умолчанию. Для Exchange 2016 выбирать Exchange 2013 (API не менялся) |
3 |
ExchangeUserLogin |
Логин (еmail) пользователя, от имени которого коннектор будет работать с EWS Managed API. |
4 |
ExchangeUserPassword |
Пароль пользователя, от имени которого коннектор будет работать с EWS Managed API. |
5 |
ExchangeUserDomain |
Домен пользователя, от имени которого коннектор будет работать с EWS Managed API. |
6 |
ExchangeEmailsPerCall |
Количество сообщений, получаемых за один запрос к серверу |
7 |
ExchangeFoldersPerCall |
Количество папок, получаемых за один запрос к серверу |
8 |
ExchangeWhiteList |
Путь к файлу со списком почтовых ящиков разрешенных для сканирования. |
9 |
ExchangeBlackList |
Путь к файлу со списком почтовых ящиков запрещенных для сканирования |
10 |
ExchangeMaxDegreeOfParallelism |
Максимальное количество параллельных потоков (не может быть больше количества ядер) |
11 |
ExchangeLogExtendedStatisticsOnly |
Ведение расширенной статистики по каждому ящику (используется для диагностики проблем получения писем из ящиков) |
Поля, использующиеся при настройке `SendToYva = true`.
Поле |
Описание |
|
1 |
UsersEndpointUrl |
Endpoint URL API Платформы Yva для загрузки пользователей. |
2 |
MailsEndpointUrl |
Endpoint URL API Платформы Yva для загрузки писем. |
3 |
AuthToken |
JWT-токен доступа к API Платформы Yva. |
4 |
MaxRequestSizeInMb |
Максимальный размер запроса к API Yva |
- Файлы whitelist.json \ blacklist.json
Пути к файлам указываются в полях `ExchangeWhiteList` и `ExchangeBlackList`.
Пример содержимого файла:
["test@test.com", "test1@test.com"]
Описание API для передачи данных в платформу
- Почта (Mails)
Добавляет письма/сообщения в Yva. Передаётся POST-запросом.
В теле запроса передается описание письм/сообщений:
{
"ownerIdentity": {
"type": "string",
"value": "string"
},
"mailMessages": [
{
"id": "string",
"sentAt": "2018-12-08T05:50:49.360Z",
"receivedAt": "2018-12-08T05:50:49.360Z",
"from": {
"displayName": "string",
"address": "string"
},
"to": [
{
"displayName": "string",
"address": "string"
}
],
"cc": [
{
"displayName": "string",
"address": "string"
}
],
"bcc": [
{
"displayName": "string",
"address": "string"
}
],
"importance": "low",
"threadId": "string",
"subject": "string",
"body": {
"contentType": "text","content": "string"
},
"headers": [
{
"name": "string",
"value": "string"
}
],
"isFlagged": true,
"isSent": true,
"isAutomatic": true
}
]
}
- Пользователи (Users)
Добавляет пользователей в Платформу. Передаётся POST-запросом.
В теле запроса передается описание пользователей:
{
"users": [
{
"id": "string",
"loginEmail": "string",
"identities": [
{
"type": "string",
"value": "string"
}
],
"firstName": "string",
"lastName": "string",
"displayName": "string",
"jobTitle": "string",
"department": "string",
"timeZoneOffset": "string"
}
]
}