OAuth 2.0 for Office 365 Accounts (non-interactive mode)

This tutorial demonstrates using OAuth 2.0 with IMAP/POP3 for Office 365 (Client Credentials flow where the end user is not required to give consent to your app's accessing their email).

Note that at the time of writing (October 2022) Office 365 still does not support Client Credentials flow for SMTP, so the classic login/password authentication (Basic Auth) is still the recommended option for SMTP. This may change in the future.

See Microsoft accounts - Installed apps or Microsoft accounts - Installed apps running HttpListener versions of this tutorial if you're looking for OAuth 2.0 for Outlook.com or Hotmail.com accounts (not Office 365).

See desktop or ASP.NET Core guide if you're looking for interactive flows where the end user grants consent to your app to access their email.

• Introduction
• Register Azure project
• Configure Exchange Online
• Get access token - Sample code

Introduction

Basically, Client Credentials flow is very simple on the application side but in case of Office 365 requires a lot of efforts to configure a number of things in your Office 365 tenant and app registration. The below is an unofficial guide which seems to work for us. It was adapted from the kind contribution of our customers and our personal experience. However, should you encounter any issues with it, we recommend contacting Office 365 techsupport directly as we cannot assist there.

Register Azure project

• Log in as your Office 365 tenant admin at https://aad.portal.azure.com.
• Azure Active Directory / App Registrations.
• Click "New Registration".
• Type some name (e.g. MailBee) and click "Register".
• Now you'll see the page where Application (client) ID and Directory (tenant) ID for your newly created app registration will be displayed. Store them for later use.
• Click "Certificates & secrets" in the menu below Search box.
• Click "New client secret".
• Set some description and expiration time (e.g. 24 months).
• Click "Add" to create your new secret.
• On Overview page, you'll see the newly created secret but only once. Copy/paste Secret Value (not Secret ID) and save it into safe location for later use (referred as Saved Client Secret below).
• Click "API permissions" in the menu below Search box.
• Click "Add a permission".
• Select "APIs my organization uses".
• Type "Office 365 Exchange Online" in the textbox.
• Click the found item.
• Select "Application Permissions" (not "Delegated Permissions").
• Select these permissions (at least): full_access_as_app, IMAP.AccessAsApp, POP.AccessAsApp. There can be other permissions added if you intent to use other protocols like Graph.
• Click "Add permissions"
• Click "Grant admin consent for CompanyName".
• Click "Enterprise applications" in the far left menu.
• Find and click your app registration.
• Copy Object ID for later use. Note that when you created an app registration earlier, you also had Object ID on Overview page. As weird as it sounds, it's different Object ID. Do not use that one (from Overview)!

Configure Exchange Online

It's now required to set permissions to impersonate user mailboxes in Exchange Online. For that, you to create a Service Principal and assign it to all mailboxes which you want to access. The mailboxes must belong to your tenant/domain.

• Install ExchangeOnlineManagement PowerShell module (if not already installed) as below:
  • Open PowerShell as Administrator.
  • Run Get-ExecutionPolicy command. Save its output for later.
  • If the output is not Unrestricted or RemoteSigned, run Set-ExecutionPolicy RemoteSigned command.
  • Run Install-Module ExchangeOnlineManagement command and confirm that it's OK to install from an untrusted repository.
  • The previous step might require the update of NuGet itself. Confirm it.
  • If NuGet fails "the corresponding package is missing in the repositories" error, it may indicate that the default TLS version used by the system is outdated. Run this then: [System.Net.ServicePointManager]::SecurityProtocol = 'Tls12' and repeat the above.
• Run Connect-ExchangeOnline command and authenticate with your tenant admin account.
• Create a Service Principal by running New-ServicePrincipal -AppId ApplicationID -ServiceId ObjectID -DisplayName AnyNameYouLike command.
• Authorize the newly created Service Principal to impersonate the mailboxes in question by running Add-MailboxPermission -Identity mailbox@yourdomain.com -User ObjectID -AccessRights FullAccess command.
• Above, ApplicationID is an "Application (client) ID" from the "App Registrations". ObjectID is an Object ID from "Enterprise applications".
• You can revert the execution policy to is former value if you changed it. Run Set-ExecutionPolicy Value command where Value is the output of the earlier Get-ExecutionPolicy command.

Get access token - Sample code

Now you can use Microsoft APIs to get the access token and pass it to MailBee.NET to log in the desired mailbox in your Office 365 tenant.

The code will be the same for desktop, console and web applications.

• Install Microsoft.Identity.Client package via NuGet (in your Visual Studio solution).
• If not already installed, install MailBee.NET Objects. For instance, as MailBee.NET NuGet package.
• Add this code to your .NET application (you need to put it into an async method because Microsoft.Identity.Client API is purely async):

// Add to the top of your code file (if not already present)
using System;
using System.Threading.Tasks;
using Microsoft.Identity.Client;
using MailBee;
using MailBee.Pop3Mail;
using MailBee.ImapMail;

...

// Add to an async method
string clientId = "Application (client) ID";
string tenantId = "Directory (tenant) ID";
string clientSecret = "Saved Client Secret";
string userEmail = "mailbox, e.g. mailbox@yourdomain.com";
string[] scopes = { "https://outlook.office365.com/.default" };
IConfidentialClientApplication confidentalApp = ConfidentialClientApplicationBuilder.Create(clientId).WithTenantId(tenantId).WithClientSecret(clientSecret).Build();
AuthenticationResult result = await confidentalApp.AcquireTokenForClient(scopes).ExecuteAsync();
string userName = result.Account?.Username;
string accessToken = result.AccessToken;
string xOAuthKey = OAuth2.GetXOAuthKeyStatic(userEmail, accessToken);

// IMAP login
Imap imap = new Imap();
await imap.ConnectAsync("outlook.office365.com", 993);
await imap.LoginAsync(null, xOAuthKey, AuthenticationMethods.SaslOAuth2, AuthenticationOptions.None, null);
await imap.DisconnectAsync();

// POP3 login
Pop3 pop = new Pop3();
await pop.ConnectAsync("outlook.office365.com", 995);
await pop.LoginAsync(null, xOAuthKey, AuthenticationMethods.SaslOAuth2, AuthenticationOptions.None, null);
await pop.DisconnectAsync();

' Add to the top of your code file (if not already present)
Imports Microsoft.Identity.Client
Imports MailBee
Imports MailBee.Pop3Mail
Imports MailBee.ImapMail

...

' Add to an async method
Dim clientId As String = "Application (client) ID"
Dim tenantId As String = "Directory (tenant) ID"
Dim clientSecret As String = "Saved Client Secret"
Dim userEmail As String = "mailbox, e.g. mailbox@yourdomain.com"
Dim scopes As String() = {"https://outlook.office365.com/.default"}
Dim confidentalApp As IConfidentialClientApplication = ConfidentialClientApplicationBuilder.Create(clientId).WithTenantId(tenantId).WithClientSecret(clientSecret).Build()
Dim result As AuthenticationResult = Await confidentalApp.AcquireTokenForClient(scopes).ExecuteAsync()
Dim userName As String = result.Account?.Username
Dim accessToken As String = result.AccessToken
Dim xOAuthKey As String = OAuth2.GetXOAuthKeyStatic(userEmail, accessToken)

' IMAP login
Dim imap As Imap = New Imap()
Await imap.ConnectAsync("outlook.office365.com", 993)
Await imap.LoginAsync(Nothing, xOAuthKey, AuthenticationMethods.SaslOAuth2, AuthenticationOptions.None, Nothing)
Await imap.DisconnectAsync()

' POP3 login
Dim pop As Pop3 = New Pop3()
Await pop.ConnectAsync("outlook.office365.com", 995)
Await pop.LoginAsync(Nothing, xOAuthKey, AuthenticationMethods.SaslOAuth2, AuthenticationOptions.None, Nothing)
Await pop.DisconnectAsync()

If you're on .NET 4.5 and experiencing TLS 1.0 related error when obtaining the token, upgrade your solution to a newer .NET version. Alternatively, add this at the top of your method which gets the access token:

System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12

The login procedure should now complete successfully.

You can find the complete sample projects based on this code (.NET 4.5+ compatible, C# and VB.NET) at these locations:

• My Documents\MailBee.NET Objects\Samples\WinForms\.NET 4.5 OAuth\C#\Office365OAuthCredentialsFlowConsoleApp
• My Documents\MailBee.NET Objects\Samples\WinForms\.NET 4.5 OAuth\VB\Office365OAuthCredentialsFlowConsoleApp

As mentioned above, the code in these console projects can be applied to desktop and ASP.NET Core apps with no changes.

Send feedback to AfterLogic

Copyright © 2006-2022 AfterLogic Corporation. All rights reserved.