Připojení k Exchange Serveru pomocí EWS a IMAP

Pro připojení k serverům Exchange 2007, 2010 a 2013 pomocí Exchange Web Service Aspose.Email poskytuje IEWSClient rozhraní, které implementuje EWSClient třída. The EWSClient.GetEWSClient metoda vytvoří a vrátí IEWSClient objekt, který je dále používán k provádění operací souvisejících s poštovní schránkou Exchange a dalšími složkami. Tento článek ukazuje, jak vytvořit instance objektů IEWSClient.

Připojení k serveru Exchange pomocí EWS

Následující úryvek kódu ukazuje, jak navázat spojení pomocí 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;
}

Přidat vlastní hlavičky při inicializaci EWSClient

V situacích, kdy jsou během inicializace klienta vyžadovány specifické hlavičky, například hlavička X-AnchorMailbox v EWS, použijte následující přetížené metody k přidání vlastních hlaviček při vytváření instance IEWSClient:

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

Níže uvedený ukázkový kód demonstruje, jak nakonfigurovat a inicializovat IEWSClient s využitím vlastních HTTP hlaviček:

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

Připojení k serveru Exchange pomocí IMAP

Microsoft Exchange Server podporuje protokol IMAP pro přístup k položkám poštovní schránky. Použijte Aspose.Email ImapClient třída pro připojení k serveru Exchange pomocí protokolu IMAP. Pro více informací o ImapClient třída. Nejprve se ujistěte, že služby IMAP jsou povoleny pro váš server Exchange:

Otevřete Ovládací panely.
Přejděte na Nástroje správce, poté Služby.
Zkontrolujte stav služby Microsoft Exchange IMAP4.
Pokud již neběží, povolte/ spusťte jej.

Následující úryvek kódu ukazuje, jak se připojit a vypsat zprávy ze složky Doručené na serveru Microsoft Exchange pomocí protokolu 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();

Následující úryvek kódu ukazuje, jak použít 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
}

Po připojení k serveru Exchange pomocí IMAP a získání IMapMessageInfoCollection, můžete získat MessageInfo objekt. Následující úryvek kódu vám ukazuje, jak použít pořadové číslo MessageInfo objekt pro uložení konkrétní zprávy.

// 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);
}

Nastavení preferovaného šifrovacího protokolu

EWS používá pro podporované operace transportní protokol HTTPS. Šifrování poskytují protokoly SSL/TLS. Tyto protokoly jsou implementovány .NET frameworkem a mohou se lišit v závislosti na aktuální verzi .NET frameworku.

Pro nastavení verze SSL/TLS použijte následující kód:

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

nebo

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

Poznámka: pokud zadaný EncryptionProtocol není podporován aktuální verzí .NET frameworku, SupportedEncryption vlastnost sníží šifrovací protokol na podporovanou úroveň a SetSupportedEncryptionUnsafe metoda vyvolá výjimku.

Připojení k Exchange Serveru pomocí moderního ověřování

Moderní ověřování je nyní ve výchozím nastavení povoleno pro všechny nové tenanty Microsoft 365/Azure, protože tento protokol je bezpečnější než zastaralé Basic Authentication.

Moderní ověřování je založeno na Active Directory Authentication Library a OAuth 2.0. Používá časově omezené tokeny a aplikace neukládají uživatelské přihlašovací údaje.

Předběžná nastavení

Pro použití moderního ověřování se ujistěte, že je povoleno. Pro tenanty vytvořené před 1. srpnem 2017 je moderní ověřování ve výchozím nastavení vypnuté. V admin centrum Microsoft 365, přejděte na Settings > Org Settings > Modern Authentication. Ve Modern authentication flyout, který se objeví, můžete zjistit protokoly, které již nevyžadují základní ověřování. U nových tenantů Microsoft365 v Azure je Basic Authentication ve výchozím nastavení pro všechny aplikace zakázáno. Proto se tento text zobrazí v této sekci.

Vaše organizace má povoleny výchozí zabezpečení, což znamená, že je vyžadováno moderní ověřování pro Exchange Online a připojení pomocí základního ověřování jsou blokována. > Před změnou jakýchkoli nastavení musíte ve Azure portálu vypnout výchozí zabezpečení.

Podporu Basic Auth pro tenant můžete povolit z Azure portálu, přejděte na Azure Active Directory > Properties > Manage Security defaults > Enable Security defaults > No. Pro více informací viz Článek dokumentace Microsoft.

Registrace aplikace v Azure Active Directory

Je nutné provést registraci aplikace v Azure Active Directory. Existují dva typy oprávnění, které lze použít k přístupu k poštovním schránkám s vaší aplikací. Vyberte konkrétní typ oprávnění podle toho, jakou aplikaci vytváříte:

Aplikace používající delegovaná oprávnění mají přihlášeného uživatele. Jinými slovy, při připojení ke službě se zobrazí dialogové okno pro zadání uživatelského jména a hesla. Aplikace nemůže mít více oprávnění než přihlášený uživatel.
Aplikace používající oprávnění aplikace běží bez přihlášeného uživatele. Například jde o aplikace běžící jako služby na pozadí nebo démoni. Pouze administrátor může udělit souhlas s oprávněními aplikace.

Kromě toho se podívejte na Článek dokumentace Microsoft pro více informací.

Postup registrace závisí na vybraném typu oprávnění. Pro registraci vaší aplikace se podívejte na Článek dokumentace Microsoft.

Použít moderní ověřování s EWSClient

Po registraci aplikace se můžeme zaměřit na psaní kódu, který bude sestávat z následujících částí:

Získat autorizační token.
Použijte token k ověření.

Získat autorizační token

K získání tokenu použijeme Microsoft Authentication Library (MSAL) pro .NET.

Následují kroky k získání autorizačního tokenu.

Přidejte balíček NuGet Microsoft.Identity.Client která obsahuje binární soubory MSAL.NET.
Vytvořte třídu AccessParameters pro uložení pověření.
Vytvořte metodu přijímající přístupové parametry a používající MSAL.NET k získání přístupového tokenu.

Následující ukázky kódu budou záviset na zvoleném typu ověření.

Získat token s delegovaným ověřením

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;
}

Získat token s autorizací aplikace

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;
}

Ověřování pomocí tokenu

Poté, když jsme úspěšně získali token, inicializujme EwsClient.

Použití tokenu s delegovaným ověřením

NetworkCredential credentials = new OAuthNetworkCredential(accessToken);

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

Vyzkoušejte to! Spusťte EWSModernAuthenticationDelegated jednoduchý projekt aplikace, připojit se k Microsoft 365 s delegovaným ověřením a číst vaši doručenou poštu.

Použití tokenu s ověřením aplikace

// 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);

Vyzkoušejte to! Spusťte EWSModernAuthenticationApp jednoduchý projekt aplikace, připojit se k Microsoft 365 s ověřením aplikace a číst vaši doručenou poštu.

Použít moderní ověřování s klienty IMAP, POP nebo SMTP

Přístup k IMAP, POP, SMTP pomocí oprávnění aplikace není podporován. Jinými slovy, podporováno je pouze delegované ověřování.

Postup registrace aplikace v Azure Active Directory je definován výše.

Povolit nebo zakázat IMAP, POP, SMTP AUTH v Microsoft 365 Admin Center

Otevřete admin centrum Microsoft 365 a přejděte na Users > Active users.
Vyberte uživatele a v zobrazeném flyoutu klikněte na Mail.
V sekci Email apps klikněte na Manage email apps.
Zkontrolujte nastavení IMAP, POP, Authenticated SMTP: nezaškrtnuto = zakázáno, zaškrtnuto = povoleno.
Klikněte na Save changes.

Získat autentizační token ze serveru tokenů

Ujistěte se, že zadáváte úplné rozsahy, včetně URL zdrojů Outlook.

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

K získání tokenu použijeme Microsoft Authentication Library (MSAL) pro .NET.

Následují kroky k získání autorizačního tokenu.

Přidejte balíček NuGet Microsoft.Identity.Client která obsahuje binární soubory MSAL.NET.
Vytvořte třídu AccessParameters pro uložení pověření.
Vytvořte metodu přijímající přístupové parametry a používající MSAL.NET k získání přístupového tokenu.

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;
}

Ověřit pomocí tokenu

Poté, když jsme úspěšně získali token, inicializujme ImapClient.

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

Podobně SmtpClient inicializace bude vypadat následovně.

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

Vyzkoušejte to! Spusťte EWSModernAuthenticationImapSmtp jednoduchý projekt aplikace, připojit se k Microsoft 365 přes IMAP a SMTP a číst doručenou poštu.

Vrátit ID požadavku klienta

The ReturnClientRequestId vlastnost byla přidána do EWSClient pro vaše pohodlí, aby bylo možné určit, zda má být ID požadavku klienta vráceno v odpovědi z volání Exchange Web Services (EWS) calls. ID požadavku klienta je jedinečný identifikátor, který můžete nastavit pro každý EWS request odeslaný z vaší aplikace. Nastavením ReturnClientRequestId nastavením vlastnosti na true indikujete, že chcete, aby ID požadavku klienta bylo zahrnuto v odpovědi ze serveru EWS. To může být užitečné pro sledování a korelování požadavků a odpovědí v situacích, kdy je odesláno a zpracováno více požadavků asynchronně.

Následující úryvek kódu ukazuje, jak lze vlastnost využít:

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();
}

Přidat X-AnchorMailbox a další hlavičky k požadavkům EWS

Aspose.Email API umožňuje přidávat hlavičky k požadavkům na Exchange. To lze použít k přidání hlaviček k požadavkům EWS pro různé účely. Jedním příkladem může být přidání hlavičky X-AnchorMailbox, která se používá k řízení problémů s přetížením na serveru Exchange. AddHeader metoda třídy IEWSClient se používá k přidání hlaviček do požadavků EWS, jak ukazuje následující úryvek kódu.

Ignorovat nebo obejít neplatný či vypršený SSL certifikát

Aspose.Email může zpracovávat SSL certifikáty na Exchange Serveru pomocí obou ExchangeClient a EWSClient tříd. Pokud SSL certifikát vypršel nebo se stal neplatným, Aspose.Email vyvolá výjimku kvůli neplatnému SSL certifikátu. Vyhněte se takovým chybám SSL certifikátu jejich ignorováním pomocí metody použitím níže uvedeného kódu. Zaregistrujte callback handler ve vaší metodě main() nebo init() a přidejte níže uvedenou metodu jako člen třídy.

Získání a správa informací o poštovní schránce Exchange Serveru pomocí EWS