Подключение к серверу Exchange с использованием EWS и IMAP

Для подключения к серверам Exchange 2007, 2010 и 2013 с использованием Exchange Web Service Aspose.Email предоставляет IEWSClient интерфейс, реализующий EWSClient класс. The EWSClient.GetEWSClient метод создает и возвращает IEWSClient объект, который далее используется для выполнения операций, связанных с почтовым ящиком Exchange и другими папками. Эта статья показывает, как создавать объекты IEWSClient.

Подключение к серверу Exchange через EWS

Следующий фрагмент кода показывает, как установить соединение с использованием Exchange Web Service (EWS):

// For complete examples and data files, please go to https://github.com/aspose-email/Aspose.Email-for-.NET
private static IEWSClient GetExchangeEWSClient()
{
    const string mailboxUri = "https://outlook.office365.com/ews/exchange.asmx";
    const string domain = @"";
    const string username = @"username@ASE305.onmicrosoft.com";
    const string password = @"password";
    NetworkCredential credentials = new NetworkCredential(username, password, domain);
    IEWSClient client = EWSClient.GetEWSClient(mailboxUri, credentials);
    return client;
}

Добавление пользовательских заголовков при инициализации EWSClient

В сценариях, когда при инициализации клиента требуются определённые заголовки, такие как заголовок X-AnchorMailbox в EWS, используйте следующие перегруженные методы для добавления пользовательских заголовков при создании экземпляра IEWSClient:

IEWSClient GetEWSClient(string mailboxUri, ICredentials credentials, WebProxy proxy, Dictionary headers)
async Task GetEwsClientAsync(string mailboxUri, ICredentials credentials, WebProxy proxy, CancellationToken cancellationToken , Dictionary headers)

Пример кода ниже демонстрирует, как настроить и инициализировать IEWSClient с использованием пользовательских HTTP-заголовков:

var headers = new Dictionary<string, string>();
headers.Add("X-AnchorMailbox", smtpExampleAddress);
IEWSClient client = EWSClient.GetEWSClient(HttpsExampleCom, new OAuthNetworkCredential("UserName", "Token"), null, headers);

Подключение к серверу Exchange через IMAP

Microsoft Exchange Server поддерживает протокол IMAP для доступа к элементам почтового ящика. Используйте Aspose.Email ImapClient класс для подключения к серверу Exchange с использованием протокола IMAP. Для получения дополнительной информации о ImapClient класс. Сначала убедитесь, что службы IMAP включены для вашего сервера Exchange:

Откройте Панель управления.
Перейдите в Административные инструменты, затем Службы.
Проверьте состояние службы Microsoft Exchange IMAP4.
Если он еще не запущен, включите/запустите его.

Следующий фрагмент кода показывает, как подключиться и вывести список сообщений из папки Inbox Microsoft Exchange Server с использованием протокола IMAP.

// For complete examples and data files, please go to https://github.com/aspose-email/Aspose.Email-for-.NET
// Connect to Exchange Server using ImapClient class
ImapClient imapClient = new ImapClient("ex07sp1", "Administrator", "Evaluation1");
imapClient.SecurityOptions = SecurityOptions.Auto;

// Select the Inbox folder
imapClient.SelectFolder(ImapFolderInfo.InBox);

// Get the list of messages
ImapMessageInfoCollection msgCollection = imapClient.ListMessages();
foreach (ImapMessageInfo msgInfo in msgCollection)
{
    Console.WriteLine(msgInfo.Subject);
}
// Disconnect from the server
imapClient.Dispose();

Следующий фрагмент кода показывает, как использовать SSL.

// For complete examples and data files, please go to https://github.com/aspose-email/Aspose.Email-for-.NET
public static void Run()
{            
    // Connect to Exchange Server using ImapClient class
    ImapClient imapClient = new ImapClient("ex07sp1", 993, "Administrator", "Evaluation1", new RemoteCertificateValidationCallback(RemoteCertificateValidationHandler));
    imapClient.SecurityOptions = SecurityOptions.SSLExplicit;

    // Select the Inbox folder
    imapClient.SelectFolder(ImapFolderInfo.InBox);

    // Get the list of messages
    ImapMessageInfoCollection msgCollection = imapClient.ListMessages();
    foreach (ImapMessageInfo msgInfo in msgCollection)
    {
        Console.WriteLine(msgInfo.Subject);
    }
    // Disconnect from the server
    imapClient.Dispose();   
}

// Certificate verification handler
private static bool RemoteCertificateValidationHandler(object sender, X509Certificate certificate, X509Chain chain, SslPolicyErrors sslPolicyErrors)
{
    return true; // ignore the checks and go ahead
}

После подключения к серверу Exchange с помощью IMAP и получения IMapMessageInfoCollection, вы можете получить MessageInfo объект. Следующий фрагмент кода показывает, как использовать порядковый номер MessageInfo объект для сохранения конкретного сообщения.

// For complete examples and data files, please go to https://github.com/aspose-email/Aspose.Email-for-.NET
// Select the Inbox folder
imapClient.SelectFolder(ImapFolderInfo.InBox);
// Get the list of messages
ImapMessageInfoCollection msgCollection = imapClient.ListMessages();
foreach (ImapMessageInfo msgInfo in msgCollection)
{
    // Fetch the message from inbox using its SequenceNumber from msgInfo
    MailMessage message = imapClient.FetchMessage(msgInfo.SequenceNumber);

    // Save the message to disc now
    message.Save(dataDir + msgInfo.SequenceNumber + "_out.msg", SaveOptions.DefaultMsgUnicode);
}

Установка предпочтительного протокола шифрования

EWS использует протокол транспортировки HTTPS для поддерживаемых операций. Шифрование обеспечивается протоколами SSL/TLS. Эти протоколы реализованы в .NET Framework и могут отличаться в зависимости от текущей версии .NET Framework.

Чтобы задать версию SSL/TLS, используйте следующий код:

var client = new ImapClient("some.host");
client.SupportedEncryption = EncryptionProtocols.Tls13;

или

var client = new ImapClient("some.host");
client.SetSupportedEncryptionUnsafe(EncryptionProtocols.Tls13);

Обратите внимание, если указанный EncryptionProtocol не поддерживается текущей версией .NET Framework, то SupportedEncryption свойство понижает протокол шифрования до поддерживаемого уровня и SetSupportedEncryptionUnsafe метод бросает исключение.

Подключение к серверу Exchange с использованием современной аутентификации

Современная аутентификация теперь включена по умолчанию для всех новых арендаторов Microsoft 365/Azure, поскольку этот протокол более безопасен, чем устаревшая базовая аутентификация.

Современная аутентификация основана на библиотеке Active Directory Authentication Library и OAuth 2.0. Она использует ограниченные по времени токены, и приложения не хранят учётные данные пользователей.

Требуемые настройки

Чтобы использовать современную аутентификацию, убедитесь, что она включена. Однако для арендаторов, созданных до 1 августа 2017 года, современная аутентификация по умолчанию отключена. В Центр администрирования Microsoft 365, перейдите в Настройки > Параметры организации > Современная аутентификация. В появившемся всплывающем окне Современная аутентификация вы сможете увидеть протоколы, которые более не требуют Basic authentication. Для новых арендаторов Microsoft365 в Azure, базовая аутентификация по умолчанию отключена для всех приложений. Поэтому данный текст будет отображён в этом разделе.

В вашей организации включены параметры безопасности по умолчанию, что означает необходимость использования современной аутентификации для Exchange Online, а соединения с базовой аутентификацией заблокированы. > Вы должны отключить параметры безопасности по умолчанию в портале Azure, прежде чем сможете изменить любые настройки здесь.

Вы можете включить поддержку Basic Auth для арендатора из Azure портал, перейдите в Azure Active Directory > Свойства > Управление параметрами безопасности > Включить параметры безопасности > Нет. Для получения дополнительной информации смотрите Статья документации Microsoft.

Регистрация приложения в Azure Active Directory

Необходимо выполнить регистрацию приложения в Azure Active Directory. Существует два типа разрешений, которые можно использовать для доступа к почтовым ящикам вашим приложением. Выберите конкретный тип разрешения в зависимости от создаваемого приложения:

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

Кроме того, см. Статья документации Microsoft для получения дополнительной информации.

Процедура регистрации зависит от выбранного типа разрешения. Чтобы зарегистрировать приложение, обратитесь к Статья документации Microsoft.

Использовать современную аутентификацию с EWSClient

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

Получить токен авторизации.
Используйте токен для аутентификации.

Получить токен авторизации

Чтобы получить токен, мы будем использовать Microsoft Authentication Library (MSAL) для .NET.

Ниже представлены шаги для получения токена авторизации.

Добавьте NuGet-пакет Microsoft.Identity.Client который содержит двоичные файлы MSAL.NET.
Создайте класс AccessParameters для хранения учётных данных.
Создайте метод, принимающий параметры доступа и использующий MSAL.NET для получения токена доступа.

Следующие образцы кода будут зависеть от выбранного типа аутентификации.

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

public class AccessParameters
{
    public string TenantId { get; set; }
    public string ClientId { get; set; }
    public string RedirectUri { get; set; } = "http://localhost";
    public string[] Scopes { get; set; } = { "https://outlook.office365.com/EWS.AccessAsUser.All" };
}

public static async Task<string> GetAccessToken(AccessParameters accessParameters)
{
    var pca = PublicClientApplicationBuilder
                            .Create(accessParameters.ClientId)
                            .WithTenantId(accessParameters.TenantId)
                            .WithRedirectUri(ccessParameters.RedirectUri)
                            .Build();

    var result = await pca.AcquireTokenInteractive(accessParameters.Scopes)
        .WithUseEmbeddedWebView(false)
        .ExecuteAsync();

    return result.AccessToken;
}

Получить токен с аутентификацией приложения

public class AccessParameters
{
    public string TenantId { get; set; }
    public string ClientId { get; set; }
    public string ClientSecret { get; set; }
    public string[] Scopes { get; set; } = { "https://outlook.office365.com/.default" };
}

public static async Task<string> GetAccessToken(AccessParameters accessParameters)
{
    var cca = ConfidentialClientApplicationBuilder
        .Create(accessParameters.ClientId)
        .WithClientSecret(accessParameters.ClientSecret)
        .WithTenantId(accessParameters.TenantId)
        .Build();

    var result = await cca.AcquireTokenForClient(accessParameters.Scopes).ExecuteAsync();

    return result.AccessToken;
}

Аутентификация с помощью токена

После этого, когда мы успешно получим токен, давайте инициализируем EwsClient.

Использование токена с делегированной аутентификацией

NetworkCredential credentials = new OAuthNetworkCredential(accessToken);

using var client = EWSClient.GetEWSClient("https://outlook.office365.com/EWS/Exchange.asmx", credentials);

Попробуйте! Запустите EWSModernAuthenticationDelegated простой проект приложения, подключитесь к Microsoft 365 с делегированной аутентификацией и прочитайте ваш входящий ящик.

Использование токена с аутентификацией приложения

// Use Microsoft365 username and access token
NetworkCredential credentials = new OAuthNetworkCredential(username, accessToken);

using var client = EWSClient.GetEWSClient("https://outlook.office365.com/EWS/Exchange.asmx", credentials);

Попробуйте! Запустите EWSModernAuthenticationApp простой проект приложения, подключитесь к Microsoft 365 с аутентификацией приложения и прочитайте ваш входящий ящик.

Использовать современную аутентификацию с клиентами IMAP, POP или SMTP

Доступ к IMAP, POP, SMTP через разрешения приложения не поддерживается. Иными словами, поддерживается только делегированная аутентификация.

Процедура регистрации приложения в Azure Active Directory определена выше.

Включить или отключить IMAP, POP, SMTP AUTH в Центре администрирования Microsoft 365

Откройте Центр администрирования Microsoft 365 и перейдите в Users > Active users.
Выберите пользователя, и во всплывающем окне нажмите Mail.
В разделе Email apps нажмите Manage email apps.
Проверьте настройку IMAP, POP, Authenticated SMTP: снято = отключено, отмечено = включено.
Нажмите Сохранить изменения.

Получить токен аутентификации с сервера токенов

Убедитесь, что указали полные области доступа, включая URL-адреса ресурсов Outlook.

IMAP: https://outlook.office.com/IMAP.AccessAsUser.All POP: https://outlook.office.com/POP.AccessAsUser.All SMTP: https://outlook.office.com/SMTP.Send

Чтобы получить токен, мы будем использовать Microsoft Authentication Library (MSAL) для .NET.

Ниже представлены шаги для получения токена авторизации.

Добавьте NuGet-пакет Microsoft.Identity.Client который содержит двоичные файлы MSAL.NET.
Создайте класс AccessParameters для хранения учётных данных.
Создайте метод, принимающий параметры доступа и использующий MSAL.NET для получения токена доступа.

public class AccessParameters
{
    public string TenantId { get; set; }
    public string ClientId { get; set; }
    public string RedirectUri { get; set; } = "http://localhost";
    public string[] Scopes { get; set; } = { 
        "https://outlook.office.com/IMAP.AccessAsUser.All", 
        "https://outlook.office.com/SMTP.Send" };
}

public static async Task<string> GetAccessToken(AccessParameters accessParameters)
{
    var pca = PublicClientApplicationBuilder
                            .Create(accessParameters.ClientId)
                            .WithTenantId(accessParameters.TenantId)
                            .WithRedirectUri(ccessParameters.RedirectUri)
                            .Build();

    var result = await pca.AcquireTokenInteractive(accessParameters.Scopes)
        .WithUseEmbeddedWebView(false)
        .ExecuteAsync();

    return result.AccessToken;
}

Аутентификация с токеном

После этого, когда мы успешно получим токен, давайте инициализируем ImapClient.

var imapClient = new ImapClient(
    "outlook.office365.com", 
    993, 
    username, 
    accessToken, 
    true);

Аналогично, SmtpClient инициализация будет выглядеть следующим образом.

var smtpClient = new SmtpClient(
    "smtp.office365.com",
    587, 
    username,
    accessToken, 
    true);

Попробуйте! Запустите EWSModernAuthenticationImapSmtp простой проект приложения, подключитесь к Microsoft 365 через IMAP и SMTP и прочитайте ваш входящий ящик.

Вернуть идентификатор клиентского запроса

Этот ReturnClientRequestId свойство было добавлено в EWSClient для вашего удобства, чтобы указать, следует ли возвращать идентификатор клиентского запроса в ответе от вызовов Exchange Web Services (EWS). Идентификатор клиентского запроса — уникальный идентификатор, который вы можете задать для каждого запроса EWS, отправляемого из вашего приложения. Установив ReturnClientRequestId установив свойство в true, вы указываете, что хотите, чтобы идентификатор клиентского запроса был включён в ответ от сервера EWS. Это может быть полезно для отслеживания и сопоставления запросов и ответов в сценариях, когда делается несколько запросов и они обрабатываются асинхронно.

Следующий фрагмент кода показывает, как можно использовать это свойство:

using (IEWSClient client = TestUtil.CreateEWSClient(user))
{
   // Client will create random id and pass it to the server.
   // The server should include this id in request-id header of all responses.
   client.ReturnClientRequestId = true;
   
   client.LogFileName = "ews.log";
   client.GetMailboxInfo();
}

Добавить X-AnchorMailbox и другие заголовки к запросам EWS

API Aspose.Email позволяет добавлять заголовки к запросам Exchange. Это может использоваться для добавления заголовков к запросам EWS для различных целей. Одним из примеров может быть добавление заголовка X-AnchorMailbox, который используется для управления проблемами ограничения пропускной способности на сервере Exchange. AddHeader метод IEWSClient используется для добавления заголовков к запросам EWS, как показано в следующем фрагменте кода.

Игнорировать или обходить недействительный или просроченный SSL‑сертификат

Aspose.Email может обрабатывать SSL‑сертификаты на сервере Exchange, используя оба ExchangeClient и EWSClient классов. Если SSL‑сертификат истёк или стал недействительным, Aspose.Email генерирует исключение из‑за недействительного SSL‑сертификата. Избегайте подобных ошибок SSL‑сертификатов, игнорируя их с помощью метода, показанного в коде ниже. Зарегистрируйте обработчик обратного вызова в методе main() или init() и добавьте указанный ниже метод как член класса.

Подключение к Exchange Server с использованием современного способа аутентификации Получение и управление информацией о почтовом ящике Exchange Server с помощью EWS