Интеграция DIRECTUM c Microsoft Office 365 через Microsoft Graph REST API

Введение

Для работы с почтой обычно используются стандартные подходы, которые уже реализованы в DIRECTUM. На одном из проектов заказчик ввиду определенных причин решил отказаться от использования программного продукта Microsoft Outlook на сервере и протоколов SMTP/IMAP. Альтернативным вариантом организации работы с электронной почтой стало решение «Интеграция DIRECTUM c Microsoft Office 365 через Microsoft Graph REST API».

Цель и задачи

Цель проекта – автоматизировать работу с сервисами Microsoft Office 365 (почта, календарь, контакты Outlook и пр.) с использованием Microsoft Graph REST API.

Задачи:

• разработать коннектор к службам Microsoft Office 365 для автоматизации запроса и обновления OAuth-токенов (маркеры доступа, access token), работы с электронными письмами из системы DIRECTUM;
• реализовать несколько вариантов авторизации по протоколу OAuth;
• адаптировать существующие сценарии для работы с Microsoft Office 365.

Возможности решения

Решение представляет собой набор компонентов системы, который позволяет выполнять следующие действия:

• создание, чтение, ответ, пересылка, отправка сообщений;
• удаление сообщений;
• изменение (для исходящих) и просмотр всех свойств сообщений;
• поиск, фильтрация, сортировка сообщений;
• добавление, получение и удаление вложений сообщения;
• сохранение писем в формате EML;
• обработка ошибок, которые возникают при работе с почтой.

Используемые технологии и подходы

Для получения доступа к определенным ресурсам Microsoft Graph требует токен. К примеру, маркер нужен для доступа к календарю пользователя, создания и отправки писем, чтения профиля. При каждом обращении к API необходимо передавать полученный маркер доступа добавлением в заголовок авторизации HTTP. Microsoft Graph поддерживает необязательные параметры запросов OData. Они позволяют ограничивать объем результатов, количество полей по каждому элементу. Возможность использования определенных параметров запросов варьируется для разных операций API. API Microsoft Graph работает по протоколу HTTPS. Все данные доступны только в формате JSON.

Для хранения настроек и данных для вызова API был разработан справочник «Настройки приложений Microsoft Azure». Для каждого потока OAuth в DIRECTUM должна быть заведена соответствующая настройка.

Карточка справочника «Настройки приложений Microsoft Azure»

Для удобства настройки решения был разработан соответствующий диалог.

Для авторизации используется механизм серверной авторизации на базе протокола OAuth 2.0. Каждый поток OAuth имеет свой порядок авторизации. Процесс взаимодействия системы DIRECTUM с Microsoft Graph в общем виде можно представить на схеме ниже.

Взаимодействие системы DIRECTUM с Microsoft Graph

В системе DIRECTUM были реализованы следующие потоки OAuth, каждый из которых обеспечивает безопасную аутентификацию и позволяет получить доступ к API из системы DIRECTUM:

1. Код авторизации (Authorization Code).

В этом случае поток основан на перенаправлении (redirection). Это означает, что система должна быть в состоянии взаимодействовать с пользователем. При регистрации указывается URI перенаправления, который используется для направления ответов обратно в систему. После получения кода мы можем применить его для получения маркера доступа к требуемому ресурсу. Срок действия кода авторизации истекает через 10 минут. Используя маркер обновления (refresh_token), маркер доступа нужно обновлять после его истечения, чтобы продолжить пользоваться запросами, поскольку их срок действия так же ограничен (3600 секунд).

2. Учетные данные клиента (Client Credentials).

В этом потоке для запроса маркера доступа используются идентификатор и секрет приложения. Имеется доступ ко всем почтовым ящикам. Используется для выполнения задач от имени зарегистрированного приложения, в нашем случае, системы DIRECTUM. Например, обеспечение доступа к информации, которая хранится в аккаунте системы на портале Azure.

3. Учетные данные владельца ресурсов (ROPC).

ROPC - один запрос: система отправляет идентификатор клиента и учетные данные пользователя, а затем получает токен в ответ. Можно использовать для выполнения фоновых задач от имени конкретного пользователя.

После успешной авторизации мы можем осуществлять запросы к API. Для доступа к ресурсу могут потребоваться особые разрешения, которые настраиваются на портале приложений Azure.

При отправке запросов в некоторых случаях могут появиться ошибки. Например, маркер обновления не имеет разрешения на определенное действие, становится устаревшим или отозванным. При возникновении ошибок система DIRECTUM получает соответствующий код ошибки, по которому можно определить причину ошибки. Для хранения кода ошибки, причин и рекомендуемых действий был разработан отдельный справочник. При получении ошибки администратор решения получает уведомление с соответствующей информацией.

Результаты

В результате использования решения достигается:

• удобство администрирования;
• повышение безопасности;
• новые возможности работы с почтой (подробная информация по ошибкам, расширенный список критериев отбора входящих сообщений за счет поддержки системных параметров запроса OData и т.д.);
• отсутствие необходимости установки специализированного ПО на сервере и рабочих местах.

Планы и возможности для развития решения

• добавление в работу большего функционала сервиса (к примеру, интеграция с задачами Outlook, календарями, работа с правилами, папками поиска и т.д.);
• одновременная работа с разными потоками OAuth;
• обеспечение доступа к аналитическим данным, предоставляемые службами Microsoft 365.