Не добавляется почтовый ящик в BPMSoft

Симптомы

Не удается добавить почтовый ящик на стороне BPMSoft.

Этапы диагностики для выявления причины проблемы

Проблема может быть следствием различных причин. Чтобы выявить их, выполните следующие шаги диагностики:

1. Проверка состояния экземпляров компонент микросервиса.
2. Проверка корректности настроек через страницу диагностики.
3. Анализ HAR-файла.
4. Анализ логов микросервиса.
5. Проверка конфигурации целевого почтового провайдера.

Проверка состояния экземпляров компонент микросервиса

В качестве первого шага диагностики необходимо выполнить проверку состояния всех экземпляров компонент микросервиса.

Способы развертывания

Для Kubernetes

Если почтовый сервис развертывался в Kubernetes, то выполните команду:
kubectl get pods --all-namespaces | grep <helm release name>
где:
<helm release name> — наименование релиза сервиса, которое указывалось перед его установкой.

Или выполните команду:
kubectl get pods -n <namespace name>
где:
<namespace name> — название пространства имен, в рамках которого производилась установка сервиса.

Для Docker

Если почтовый сервис развертывался в Docker, то выполните команду:
docker ps -a --filter "name=Exchange"

Анализ состояния

Если хотя бы один из контейнеров компонентов почтового сервиса находится в состоянии, отличном от «Running» или «Up», проведите диагностику инфраструктуры сервиса для проверки сетевой связности компонентов и рационального использования ресурсов, выделенных для этих компонентов.

Для диагностики можно воспользоваться командами kubectl describe для Kubernetes или docker inspect для Docker.

Если поды/контейнеры всех компонентов сервиса находятся в состоянии «Running» или «Up», то перейдите к шагу Проверка корректности настроек через страницу диагностики.

Проверка корректности настроек через страницу диагностики

Выполните полную проверку корректности настройки сервиса синхронизации почты через интерфейс диагностика. Подробнее: Самостоятельная диагностика проблем сервиса синхронизации почты.

В ходе проверки могут быть обнаружены следующие проблемы:

1. Ошибка «Unable to connect to the remote server».
2. Ошибка «The remote name could not be resolved: '##domain_name##'».

Если в ходе самостоятельной диагностики не обнаружено проблем, то перейдите к шагу Анализ HAR-файла.

Анализ HAR-файла

В ходе воспроизведения проблемы с добавлением почтового ящика необходимо сформировать HAR-файл и выполнить его анализ. Подробнее про создание HAR-файла: Как записать HAR-файл.

В ходе проверки могут быть обнаружены следующие проблемы:

1. Ошибка повторной регистрации целевого почтового ящика.
2. Ошибка «The remote server returned an error: (401) Unauthorized».
3. Ошибка «The server encountered an error processing the request. See server logs for more details».

Если в ходе анализа HAR-файла не обнаружено проблем, то перейдите к шагу Анализ логов микросервиса.

Анализ логов микросервиса

Необходимо провести анализ логов, относящихся к работе почтового микросервиса Exchange Listener, за временной интервал, в течение которого возникает ошибка при регистрации нового почтового ящика.

В случае добавления почтового провайдера с типом Exchange, требуется проверить следующие логи:

• log и Error.log на стороне платформы BPMSoft;
• Логи самого почтового микросервиса Exchange Listener.

В ходе проверки могут быть обнаружены следующие проблемы:

1. Ошибка доступа.
2. Ошибка отправки тестового письма.
3. Ошибка «The remote server returned an error: (401) Unauthorized».
4. Ошибка «The remote host closed the connection».

Проверка конфигурации целевого почтового провайдера

Необходимо проверить, соответствует ли конфигурация целевого почтового провайдера (/ClientApp/#/MailboxSettings) в BPMSoft требованиям интеграции с почтовым сервером. Администраторы сервера должны сделать вывод о соответствии настроек требованиям взаимодействия с почтовым сервером.

Ошибка настроек целевого провайдера

В ходе проверок настроек целевого провайдера были обнаружены следующие ошибки:

1. В блоке настроек «Сервер входящей почты (IMAP)» приведены неверные значения.
2. В блоке настроек «Сервер исходящей почты (SMTP)» приведены неверные значения.
3. В блоке «Дополнительные настройки» выбран неверный формат логина или при ручном указании логина установлено неверное значение.

Валидация настроек целевого провайдера

Необходимо скорректировать настройки целевого почтового провайдера в BPMSoft:

1. Блок «Сервер входящей почты (IMAP)» — настройка параметров входящей синхронизации почты.
   • «Адрес сервера» - адрес IMAP-сервера.
   • «Порт» — необходимо выбрать порт 993 для установления зашифрованного соединения или порт 143 для установления незашифрованного соединения соответственно;
   • «Безопасность» — необходимо выбрать SSL/TLS для использования стандартных протоколов безопасности при передаче данных или отсутствие настроек безопасности.
2. Блок «Сервер исходящей почты (SMTP)» — настройка параметров исходящей синхронизации почты.
   • «Адрес сервера» - адрес SMTP-сервера.
   • «Порт» — выберите порт 465 для установления зашифрованного соединения или 587, 25 для установления незашифрованного соединения.
   • «Безопасность» — выберите SSL/TLS для использования стандартных протоколов безопасности при передаче данных, STARTTLS — установка соединения без шифрования с дальнейшим переходом сессии к зашифрованному виду или отсутствие настроек безопасности.
3. Блок «Формат логина» — формат имени учетной записи, в отношении которой происходит взаимодействие с почтовым сервером. В приложении существует три возможных варианта формата:
   • «Формировать вручную» — в процессе добавления почтового ящика в приложении логин учетной записи почты для аутентификации на стороне почтового сервера указывается отдельно от email-адреса;
   • «Использовать email» — в процессе добавления почтового ящика в приложении в качестве логина учетной записи почты используется email-адрес;
   • «Использовать имя почтового ящика» — в процессе добавления почтового ящика в приложении в качестве логина используется часть email-адреса без учета почтового домена (до символа «@»).
4. «Название сервиса» — отображаемое имя почтового провайдера.
5. «Метод аутентификации» — подход к проверке подлинности учетной записи почты, от имени которой осуществляется взаимодействие с почтовым сервером. В системе реализовано два метода:
   • «Basic» — схема аутентификации, в соответствии с которой почтовому серверу для проверки подлинности предоставляется пара логин/пароль, закодированная с использованием Base64;
   • «OAuth 2.0» — протокол авторизации, в соответствии с которым доступ к почтовому серверу организовывается без необходимости передачи логина/пароля учетной записи почты (при этом пароль от почтового ящика не хранится в приложении). Вместо этого для предоставления разрешений на доступ к почте используются токены доступа. В BPMSoft данный подход используется только для синхронизации писем почтовых ящиков провайдера Microsoft 365.
     • «Идентификатор приложения (Клиент)» - идентификатор, назначенный приложению при его регистрации сервером авторизации. Подробнее: Стандарт RFC 6749.
     • «Секрет клиента» - значение секрета клиента, сформированное для приложения на портале регистрации. Подробнее: Стандарт RFC 6749.

Причины и решения

Ошибка «Unable to connect to the remote server»

В блоке «Проверка доступности сервиса» результатов диагностики фиксируется ошибка:
"Сервис ExchangeListener в данный момент не доступен для текущего сайта Unable to connect to the remote server"

В блоке «Получение информации по подпискам» результатов диагностики фиксируется ошибка:
"Http failure response for {BPMSoft_URL}/0/rest/MailDiagnosticToolsService/GetSubscribersInfo: 500 OK"

Решение

Необходимо проверить:

• В системной настройке «ExchangeListenerServiceUri» указан корректный адрес API почтового сервиса: {EL_API_URL}/api/listeners;
• Убедиться в отсутствии влияния компонентов, которые выполняют функции балансировщика нагрузки или прокси (при их наличии), на возникновение проблемы;
• Убедиться в наличии сетевой связности между серверами BPMSoft и почтового сервиса по пути: BPMSoft → ExchangeListener.

Чтобы проверить подключение, можно отправить запрос с компьютера, на котором установлено приложение BPMSoft, и проанализировать состояние инфраструктуры на основе результатов запроса:
curl {EL_API_URL}/api/listeners/status -v

Ошибка «The remote name could not be resolved: '##domain_name##'»

В блоке «Проверка доступности сервиса» результатов диагностики фиксируется ошибка:
"Сервис ExchangeListener в данный момент не доступен для текущего сайта
  The remote name could not be resolved: '##domain_name##'"

В блоке "Получение информации по подпискам" результатов диагностики фиксируется ошибка:
"Http failure response for {BPMSoft_URL}/0/rest/MailDiagnosticToolsService/GetSubscribersInfo: 500 OK"

Решение

Необходимо проверить:

• В системной настройке «ExchangeListenerServiceUri» в адресе API почтового сервиса указано корректное доменное имя;
• Убедиться в отсутствии влияния со стороны DNS-сервера и его конфигурации на возникновение проблемы.

Ошибка повторной регистрации целевого почтового ящика

В HAR-файле запрос
POST {BPMSoft_URL}/0/rest/MailboxSettingsService/GetMailboxOwners
содержит непустой результат, например:
{"GetMailboxOwnersResult":["Supervisor"]}
и отсутствует следующий запрос:
POST {BPMSoft_URL}/0/rest/MailboxSettingsService/IsServerValid

Решение

Данное поведение означает, что целевой почтовый ящик ранее уже был зарегистрирован от имени учетной записи, указанной в теле успешного ответа .../MailboxSettingsService/GetMailboxOwners. В таком случае следует выполнять по порядку следующие действия:

• Убедиться, что регистрируемый почтовый ящик отсутствует в списке добавленных ящиков в системе от имени целевого пользователя и при необходимости скорректировать наименование регистрируемого ящика;
• Произвести очистку кэша Redis и повторно выполнить регистрацию почтового ящика;
• Если необходимый почтовый ящик ранее добавил в приложении другой пользователь системы, то необходимо проверить наличие соответствующих прав у целевого пользователя для работы с уже существующим почтовым ящиком;
• Если необходимый почтовый ящик ранее добавил в приложении целевой пользователь системы, то необходимо предоставить доступ к почтовому ящику для Supervisor посредством следующего SQL-запроса:
   UPDATE MailboxSyncSettings
   SET IsShared = 1
   WHERE MailboxName = '{mailbox_name}';

Под учетной записью Supervisor в настройках почтового ящика выдать права целевому пользователю.

Ошибка «The remote server returned an error: (401) Unauthorized»

В HAR-файле, в результате выполнения запроса:
.../rest/Office365OAuthAuthenticator/ProcessAuthenticationCode?code={значение}

в заголовках ответа или в cookies (например, OAuthAuthenticate) фиксируются ошибки следующего вида:

System.AggregateException: One or more errors occurred. ---> System.Net.WebException: The remote server returned an error: (401) Unauthorized.
	at System.Net.HttpWebRequest.EndGetResponse(IAsyncResult asyncResult)
	at System.Threading.Tasks.TaskFactory`1.FromAsyncCoreLogic(IAsyncResult iar, Func`2 endFunction, Action`1 endAction, Task`1 promise, Boolean requiresSynchronization)
--- End of stack trace from previous location where exception was thrown ---
	at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
	at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
	at BPMSoft.Social.OAuth.OAuthAuthenticatorUtilities.<SendRequestAsync>d__6.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
	at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()
	at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
	at BPMSoft.Social.OAuth.OAuthAuthenticatorUtilities.<SendRequest>d__8.MoveNext()
--- End of inner exception stack trace ---
	at System.Threading.Tasks.Task`1.GetResultCore(Boolean waitCompletionNotification)
	at BPMSoft.Social.OAuth.OAuthAuthenticator.SendRequest(String url, NameValueCollection parameters)
at BPMSoft.Social.OAuth.OAuthAuthenticator.ProcessAuthenticationCode(String code)

Решение

Следует выполнить следующие проверки:

1. Убедиться, что срок действия секрета клиента (client secret), выпущенного для целевого проекта в Azure, не истёк.
2. Убедиться, что в целевой записи почтового провайдера указано актуальное значение секрета клиента в поле «Секрет клиента».
3. Убедиться, что в системе присутствует только один почтовый провайдер для Microsoft 365 (Office 365), использующий метод аутентификации OAuth 2.0. На уровне базы данных это означает наличие единственной строки в таблице OAuthApplications со значением Office365OAuthAuthenticator в столбце AppClassName.

Если эти условия не соблюдаются, необходимо:

• Определить и проанализировать существующие записи почтовых провайдеров;
• Удалить неактуальные или неиспользуемые записи;
• Оставить только одну актуальную запись почтового провайдера Office 365 с OAuth-аутентификацией, к которой были или будут привязаны почтовые ящики.

Для удаления лишних записей почтовых провайдеров в BPMSoft необходимо выполнить следующие действия:

1. Откройте запись провайдера и в поле «Метод аутентификации» установите значение «Basic», после чего нажмите кнопку «Применить» для сохранения изменений.
2. Перейдите на страницу списка почтовых провайдеров:
   {bpmsoft_url}/0/ClientApp/#/MailboxSettings.
3. Выберите нужную запись и нажмите «Удалить».

Ошибка «The server encountered an error processing the request. See server logs for more details»

В HAR-файле, в результате выполнения запроса:
.../rest/Office365OAuthAuthenticator/ProcessAuthenticationCode?code={значение}

в теле ответа фиксируется ошибка следующего вида:

<?xml version = "1.0" encoding = "utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns = "http://www.w3.org/1999/xhtml">
<head>
	<title>Request Error</title>
	<style>
		…
	</style>
</head>
<body>
	<div id = "content">
		<p class="heading1">Request Error</p>
		<p>The server encountered an error processing the request. See server logs for more details.</p>
	</div>
</body>
</html>

Решение

Следует выполнить следующие проверки:

1. Проверить наличие необходимых правил межсетевого экрана (firewall), обеспечивающих корректную обработку входящих и исходящих запросов, инициируемых со стороны Azure.
2. При наличии балансировщика нагрузки или промежуточного прокси-сервера — проверить их конфигурацию и влияние на маршрутизацию трафика, в том числе на возможность возникновения сбоев в процессе аутентификации или взаимодействия с внешними сервисами.

Ошибка доступа

В логах почтового сервиса фиксируются ошибки вида:

ImapClient instance to ##mail server address##:993 for login ##email login## failed. - System.TimeoutException: The operation has timed out. 
at MailKit.Net.SocketUtils.ConnectAsync(String host, Int32 port, IPEndPoint localEndPoint, Int32 timeout, Boolean doAsync, CancellationToken cancellationToken)

Или ошибка:

exception = SmtpCommandException, message = connections from your host are denied
exception = ImapProtocolException, message = Syntax error in IMAP server greeting. Unexpected atom token: NO

Решение

Если клиентский почтовый сервис Exchange Listener и почтовый сервер находятся в разных сетях и доступ к серверу ограничен безопасностью, рекомендуется добавить адрес развёртывания Exchange Listener в белый список почтовой инфраструктуры и провести дополнительные проверки на уровне инфраструктуры сервера для исключения сетевых ошибок.

Ошибка отправки тестового письма

В логах почтового сервиса фиксируются ошибки вида:

SmtpClient instance to ##mail server address##:465 for login ##email login## failed. - MailKit.Security.SslHandshakeException: An error occurred while attempting to establish an SSL or TLS connection.

Решение

В данном случае в процессе регистрации почтового ящика не отправляется тестовое проверочное письмо из BPMSoft.

Для проверки выполните следующие действия:

1. Подключитесь к стороннему почтовому клиенту (например, Thunderbird) и проверьте возможность отправки писем с вашего почтового домена.
2. Убедитесь, что версии криптографических протоколов, используемых почтовой инфраструктурой (SMTP-сервер), совместимы с версиями протоколов на стороне клиентского приложения (Exchange Listener).

Ошибка «The remote server returned an error: (401) Unauthorized»

В логах BPMSoft (файл ExchangeListener.log) фиксируется ошибка следующего вида:

IsServerValid - Mailbox didn't pass validation with these credentials, info: Microsoft.Exchange.WebServices.Data.ServiceRequestException: The request failed. The remote server returned an error: (401) Unauthorized.
---> System.Net.WebException: The remote server returned an error: (401) Unauthorized.
	…
	at Microsoft.Exchange.WebServices.Data.ExchangeService.BindToFolder(FolderId folderId, PropertySet propertySet)
	at Microsoft.Exchange.WebServices.Data.ExchangeService.BindToFolder[TFolder](FolderId folderId, PropertySet propertySet)
	at ExchangeListener.EwsApi.ExchangeListenerService.ValidateSynchronizationCredentials() in /src/ExchangeListener/EwsApi/ExchangeListenerService.cs:line 80
	at ListenerBase.Service.Service.Validate() in /src/ListenerBase/Service/Service.cs:line 246

Решение

Необходимо проверить правильность ввода логина и пароля, используемых для подключения почтовой учётной записи в BPMSoft. Также следует проанализировать логи IIS (%SystemDrive%\inetpub\logs\LogFiles), журналы событий (event-логов) и другие трассировочные файлы, которые могут содержать информацию о причинах возникших ошибок на всех узлах почтового сервера.

Ошибка «The remote host closed the connection»

В логах BPMSoft (файл Error.log) фиксируется ошибка следующего вида:

BPMSoft.Web.Common.ServiceModel.ErrorHandler HandleError - AssemblyQualifiedServiceName = [BPMSoft.Configuration.TestService.MailboxSettingsService, BPMSoft.Configuration, Culture=neutral, PublicKeyToken=null]
System.ServiceModel.CommunicationException: The remote host closed the connection. The error code is 0x80070057. ---> System.Web.HttpException: The remote host closed the connection. The error code is 0x80070057.

В логах почтового сервиса фиксируется значительное время каждого отдельно взятого взаимодействия с Exchange EWS. Например:

2023-09-08 09:23:37,467 [18] INFO : [] [{mailbox_name}] Exchange service {mail_server_address} instance for user {bpm_user} created.
(01:40 - время выполнения запроса к EL /api/mailbox/validate)
2023-09-08 09:25:17,705 [23] INFO : [] [{mailbox_name}] Exchange service {mail_server_address} instance for user {bpm_user} created.
2023-09-08 09:25:17,705 [23] INFO : [03bbb03a-91c7-4d74-baed-53f5bf448f68_s] [00000000] Start processing send command.
2023-09-08 09:25:17,705 [23] INFO : [03bbb03a-91c7-4d74-baed-53f5bf448f68_s] [00000000] Subject: 'Тестовое сообщение, Sender: '{mailbox_name}', Id: '{message_id}' to '{mail_server_address}:0'.
2023-09-08 09:26:58,297 [23] INFO : [03bbb03a-91c7-4d74-baed-53f5bf448f68_s] [00000000] Email with subject 'Тестовое сообщениеsent.
2023-09-08 09:26:58,297 [23] INFO : [03bbb03a-91c7-4d74-baed-53f5bf448f68_s] [00000000] Finnished processing send command
(01:40 - время выполнения запроса к EL /apiv2/email/send)

Решение

Необходимо провести анализ маршрутизации сетевого трафика от клиентского приложения (ExchangeListener), размещённого в окружении k8s/docker, до почтового сервера, а также, при необходимости, скорректировать настройки межсетевого экрана (FW) для обеспечения доступа по требуемым портам на стороне почтового сервера.

По умолчанию приложение устанавливает соединение с конечной точкой https://{адрес_почтового_сервера}/EWS/Exchange.asmx по защищенному порту 443 (маршрут: k8s/docker → exchange:443). Однако в зависимости от конфигурации почтового сервера может потребоваться разрешить доступ также и по порту 80 (маршрут: k8s/docker → exchange:80).

Одна из возможных причин заключается в следующем: если на почтовом сервере используется самоподписанный сертификат, проверка его статуса может требовать получения списка отозванных сертификатов (CRL), доступ к которому осуществляется по адресу, указанному в соответствующем поле сертификата. Такой ресурс, как правило, доступен по протоколу HTTP (порт 80). В связи с этим для корректной работы подключения к почтовому серверу необходимо обеспечить доступ к порту 80 на его стороне.

Рекомендуем изучить

Сервис синхронизации почты