OAuth | EighTwOne (821)

Update 22feb2021: Added note about enabling SMTP Authentication.

Not too long ago, the Exchange product group enabled Modern Authentication (or OAuth2) support for IMAP and SMTP in Exchange Online, and shortly after for POP3 as well. This support was much needed with the imminent deactivation of Basic Authentication. With Modern Authentication available, vendors, developers as well as organizations running custom scripts are given time to adopt Modern Authentication where applicable.

By delaying the original end date of Basic Authentication from October 13, 2020 to Q3’ish 2021 due to the Corona situation, the adoption period is increased significantly. That does not mean however developers and organizations can sit back and relax: Act sooner rather than later, the end of Basic Authentication is nigh.

The benefits of Modern Authentication are of course that it is a more secure model (e.g. resistant to password spray attacks), as well that it can leverage Microsoft 365 functionality like Conditional Access to limit protocols to certain locations.

That said, in this article I will show you how to approve usage of a popular 3^rd party e-mail application Thunderbird, using IMAP protocol in conjunction with the Modern Authentication scheme. The procedures below have been run against Thunderbird 78.0b4 on Windows as well as Ubuntu.

Third Party Applications
Before we move on to Thunderbird, we first make sure the organization settings allow for third party applications to access your mailbox Exchange Online. This process has been blogged about for common popular applications, such as the native iOS Mail app or the Gmail app on Android. So, how to go ahead if your organization restricts access to third party applications, and they only want to allow specific applications, which is of course good practice.

The easiest way to add Thunderbird to the allowed applications and grant consent to the organization, is by constructing an admin consent URL. To construct the consent URL, take the following URL:

https://login.microsoftonline.com/<TenantID>/oauth2/authorize?client_id=<AppID>&response_type=code&prompt=admin_consent

and,

Replace <TenantID> with your Tenant ID. This piece of information can be found under the Azure Active Directory blade in the Azure portal.
Replace <AppID> with the Application ID (sometimes also referred to as Client ID) of the application you want to provide consent for. As we can see in the table below, the ID of Thunderbird is 08162f7c-0fd2-4200-a84a-f25a4db0b584.

Application	ID
Thunderbird	08162f7c-0fd2-4200-a84a-f25a4db0b584
Gmail app	2cee05de-2b8f-45a2-8289-2a06ca32c4c8
iOS Accounts (Apple Mail app)	f8d98a96-0999-43f5-8af3-69971c7bb423

Open your browser, and visit this URL as an administrator. You will be greeted with a consent form, in which you will be asked to accept for your organization. Because the redirect_uri is empty here, you will likely be send to a non-existing location after giving consent, but that’s OK.

When you look at the Enterprise Applications blade in the Azure Portal, you will notice the Thunderbird app has been added. Here you can further customize it, like any enterprise application supporting Modern Authentication, e.g.

Restrict access to specific users or groups.
Use Conditional Access to restrict access to certain locations.

Another thing to note is that permissions for Thunderbird app will have been translated to the following Graph permissions:

API	Permission	Type
Microsoft Graph	Read and write access to mailboxes via IMAP.	Delegated
Microsoft Graph	Read and write access to mailboxes via POP.	Delegated
Microsoft Graph	Read and write access to mailboxes via SMTP AUTH.	Delegated
Microsoft Graph	Sign in and read user profile.	Delegated

We should now be ready on the back-end.

Thunderbird
Now as an end user, start Thunderbird. Do not start configuring the account yet, as we first need to modify a Thunderbird setting to allow for successful Modern Authentication through a browser popup. Click the ‘hamburger’ menu to open the Options window. Scroll all the way down, and open the Config Editor. Click ‘I Accept the risk’. In the settings overview, set General.UserAgent.CompatMode.Firefox setting to True:

Preference Name	Status	Type	Value
general.useragent.compatMode.firefox	modified	boolean	True

Close the Config Editor and Preferences tab. We can now set up our account in Thunderbird.

Select Add Mail Account, and enter your name and e-mail address. You can leave the password empty, as we will be using an Oauth token which we will retrieve later on. Press Continue to have Thunderbird figure out where your mailbox is hosted. When it properly discovers the mailbox location, it will set the configuration as follows:

If Thunderbird can’t figure out your settings (for some reason the Windows build could, but the Ubuntu build couldn’t), configure them as indicated above. We can’t select OAuth2 for authentication here, so leave Authentication as is; we will correct this right after we click Done.

Note: Configure manually would be the place you expect to set authentication to OAuth2 straight away, but with the build we used, the OAuth2 option is not available from the manual account setup dialog. Therefore, we need to set up the account and correct settings afterwards.

In the Server Settings window related to your account, select OAuth2 authentication:
In the Outgoing Server (SMTP) settings, select Offic365 (Microsoft) – smtp.office365.com, click Edit and set authentication for outbound SMTP to OAuth2 as well.
Note: The Thunderbird build running on Ubuntu doesn’t provide the OAuth2 authentication option for SMTP.

When finished, click ‘Get Messages’. The familiar Microsoft 365 authentication browser dialog should show up. After signing in, the next question will be to grant consent to the Thunderbird application to it can access your mailbox data and send e-mail:

Note that this dialog can not be suppressed, as currently only interactive applications are supported. If you are working on an app or script which needs unattended access, please use Graph API.

After the user provides consent, Thunderbird is ready and will start fetching your default folders and mail items. If you want to view additional folders, you need to subscribe to them by right-clicking the account and picking Subscribe. Only folders with mail-items are supported, despite you can select every folder in your mailbox including Calendar or Contacts.

Note: If you encounter problems sending messages, please check the CASMailbox setting SmtpClientAuthenticationDisabled. If it is set to $true, you need to disable it to enable SMTP authentication, e.g.

Set-CASMailbox -Identity michel@contoso.com -SmtpClientAuthenticationDisabled $false

Logging
If you have people in your organization requiring some form of proof that Modern Authentication is being used, you can use the Enterprise Applications / Sign-Ins view from the Azure Active Directory portal.

Alternatively, you can use Thunderbird’s built-in logging capabilities. To accomplish the latter, set the following environment variables before starting Thunderbird:

MOZ_LOG=IMAP:5,timestamp
MOZ_LOG_FILE=%APPDATA%\ThunderBird-imap.log

In the generated ThunderBird-imap.log file like shown below, you should be able to spot Modern Authentication (XOAuth2) being selected:

2020-06-30 13:10:16.726000 UTC - [(null) 15696: IMAP]: I/IMAP 259C3800:outlook.office365.com:NA:CreateNewLineFromSocket: * CAPABILITY IMAP4 IMAP4rev1 AUTH=PLAIN AUTH=XOAUTH2 SASL-IR UIDPLUS MOVE ID UNSELECT CHILDREN IDLE NAMESPACE LITERAL+2020-06-30 13:10:16.726000 UTC - [(null) 15696: IMAP]: D/IMAP ReadNextLine [stream=1991DE80 nb=28 needmore=0]
2020-06-30 13:10:16.726000 UTC - [(null) 15696: IMAP]: I/IMAP 259C3800:outlook.office365.com:NA:CreateNewLineFromSocket: 1 OK CAPABILITY completed.
2020-06-30 13:10:16.726000 UTC - [(null) 15696: IMAP]: D/IMAP Try to log in
2020-06-30 13:10:16.726000 UTC - [(null) 15696: IMAP]: D/IMAP IMAP auth: server caps 0x840087635, pref 0x800000000, failed 0x0, avail caps 0x800000000
2020-06-30 13:10:16.726000 UTC - [(null) 15696: IMAP]: D/IMAP (GSSAPI = 0x1000000, CRAM = 0x20000, NTLM = 0x100000, MSN = 0x200000, PLAIN = 0x1000, LOGIN = 0x2, old-style IMAP login = 0x4, auth external IMAP login = 0x20000000, OAUTH2 = 0x800000000)
2020-06-30 13:10:16.726000 UTC - [(null) 15696: IMAP]: D/IMAP Trying auth method 0x800000000
2020-06-30 13:10:16.726000 UTC - [(null) 15696: IMAP]: D/IMAP IMAP: trying auth method 0x800000000
2020-06-30 13:10:16.726000 UTC - [(null) 15696: IMAP]: D/IMAP XOAUTH2 auth
2020-06-30 13:10:16.775000 UTC - [(null) 15696: IMAP]: D/IMAP ReadNextLine [stream=280D87C0 nb=180 needmore=0] 2020-06-30 13:10:16.775000 UTC - [(null) 15696: IMAP]: I/IMAP 2089A000:outlook.office365.com:NA:CreateNewLineFromSocket: * OK The Microsoft Exchange IMAP4 service is ready. [QQBNADQAUABSADAAMQAwADEAQwBBADAAMAA3ADYALgBlAHUAcgBwAHIAZAAwADEALgBwAHIAbwBkAC4AZQB4AGMAaABhAG4AZwBlAGwAYQBiAHMALgBjAG8AbQA=]

Updated May 9th: Added Share to Teams. to table

With the emergency to facilitate working from home due to the Corona pandemic, many organizations were faced with a dilemma. When running Exchange 2013 or some even Exchange 2010 on-premises, and a desire to start using Microsoft Teams, organizations were confronted with the following requirements for integrating Microsoft Teams with Exchange on-premises (source):

Users with mailboxes hosted on-premises must be synchronized to Azure Active Directory.
Running Exchange 2016 Cumulative Update 3 or later on-premises.
OAuth needs to be configured (via Hybrid Configuration Wizard, or manual as MVP fellow Jaap blogged about here).
Recently, an additional requirement was added to explain that for delegates to schedule calendar meetings on behalf of another person, some additional steps are required (steps 2-3 mentioned here).

Now as you might know, Exchange 2010 does not support OAuth authentication. But, by putting Exchange 2016 in front of Exchange 2010, Exchange 2016 can be used for dealing with OAuth authentication, as well as dealing with client traffic as it can down-level proxy to Exchange 2010 for mailboxes hosted on those servers. Looking at these requirements, organizations might conclude that putting Exchange 2016 CU3 in front of their Exchange environment, and configuring OAuth would suffice the requirement to integrate Teams with their Exchange on-premises environment.

Alas, the additional requirement for full Teams integration is that the mailbox server hosting the mailbox should support REST API. Teams leverages Graph REST API calls to interact with mailboxes. In an Hybrid Exchange setup, on-premises mailboxes are identified, and related REST API calls will be directed at the on-premises REST endpoint, landing on your Exchange environment. The requirement for REST API support is something which is not explicitly stated in the Teams integration article, despite my earlier pull request.

It is however stated implicitly in an article on REST support in Hybrid Exchange or the original publication on REST API support in Exchange 2016 CU3 by the Exchange PG, two articles which you might easily have missed or forgotten about. Either way, it states that “All on-premises mailboxes that will use the REST APIs must be located on databases located on Exchange 2016 CU3 servers”.

Thus, with REST API support only being available per Exchange 2016 CU3, Teams will not fully integrate with mailboxes hosted on earlier versions of Exchange. Exchange 2016 can be used to offload OAuth when your mailbox is still on Exchange 2010 (which works fine for Exchange Web Services for Free/Busy, for example), but Exchange 2010 does not support REST API, and thus will never understand those ‘weird’ (proxied) requests landing on /api virtual directory, typical of REST API calls. Consequently, you will see AutodiscoverV2 and REST API calls greeted with a 404:

2020-04-29 20:22:52 fd86:b628:2775:1:9502:cdcc:d4b1:5950 GET /autodiscover/autodiscover.json Email=chefke%40contoso.com&Protocol=REST&RedirectCount=1 443 CONTOSO\EX2$ fd86:b628:2775:1:9f8:2d9:c8a1:3c4a SkypeSpaces/1.0a$*+ 404 0 2 31

Typically, first thing users usually will notice missing is the Calendar integration:

Knowing this, the assumption could be that this combination doesn’t work at all, but as often the truth lies somewhere in the middle. You can use Teams when mailboxes are still hosted on pre-Exchange 2016 CU3, if you can live with the limitations. Below I have included a short overview of these, or other noteworthy items. The information is complementary to the How Exchange and Teams interact article. I hope it may help in discussions on what works and what doesn’t.

Disclaimer: Validated with mailbox hosted on Exchange 2010 with Exchange 2016 in front, OAuth and SkypeOnline AppId configured, and using Outlook 2016 C2R. Information may be subject to change. The list may not be conclusive; if you have any additional observations, please leave them in the comments.

Actions	Works	Comment
Create & View Meetings in Teams	No	No Calendar integration as this requires Outlook Calendar REST API. Visual clue is absence of the Calendar button.
Modify User Photo in Teams (client)	No	Doesn’t work when mailbox is hosted in Exchange on-premises.
Call History	Yes	History propagates to mailboxes hosted in Exchange on-premises in ‘Teams Calls’ folder.
Access Outlook Contacts	No	Works only with Exchange Online mailboxes.
Voicemail	Yes	May use & receive voice-mail, but can’t play from Teams.
Free/Busy status	Yes	Uses EWS.
Create & View/Update Teams Meetings from Outlook	Yes	Using default Teams Meeting add-in.
Create Teams Meetings from Outlook as Delegate	No	Teams Scheduler uses AutodiscoverV2 to discover delegate EWS endpoint, and fails. Outlook will display “Sorry, but we can’t connect to the server right now. Please try again later.”
View/Update Teams Meetings from Outlook as Delegate	Yes	EWS is used to fetch and update the calendar item.
MailTips in Teams	No	MailTips like Out of Office are not shown in Teams. MailTips work for Exchange 2016 CU3+.
Create & View Channel Meetings in Teams	No	Doesn’t work when mailbox is hosted in Exchange on-premises.
Share to Teams	No	Doesn’t work when mailbox is hosted in Exchange on-premises.

Of course, the better experience is to be had when your mailbox is hosted on Exchange 2016 CU3 or later (including Exchange 2019), or best when you simply host them in Exchange Online. However, given the circumstances and pressure from the organization to use Teams, that route might not be an option for everyone. Organizations may look at substantial investments in time and resources. In those cases, it might be good to know of alternative less preferable scenarios, and more important, any possible limitations you might encounter when taking a shortcut.