Configuring Exchange Online with IMAP & OAuth2

Posted on July 1, 2020 by Michel de Rooij

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=]

36 thoughts on “Configuring Exchange Online with IMAP & OAuth2”

evegter on July 1, 2020 at 9:02 AM said:

Hi Michel,

What version of Thunderbird are you using? The beta channel?

Thanks,
Eric

LikeLike

Reply ↓
- Michel de Rooij on July 1, 2020 at 9:05 AM said:
  
  78.0b4 to be exact (Windows & Ubuntu). Was mentioned, but I’ll mention the builds more clearly.
  
  LikeLike
  
  Reply ↓
evegter on July 1, 2020 at 10:30 AM said:

ok, thanks! I see it now indeed. Must have missed that, sorry. I have used that version too the last few weeks to access (shared)mailboxes with MFA in o365. Didn’t have to set that ‘general.useragent.compatMode.firefox’ option though. Good post, thanks!

LikeLike

Reply ↓
- Michel de Rooij on July 2, 2020 at 12:45 PM said:
  
  Thanks, so it’s a YMMV. I had to set it on Ubuntu. I normally only refer to non-default settings, e.g. Javascript also needs to be enabled (which it is by default).
  
  LikeLike
  
  Reply ↓
- J Roy on November 16, 2020 at 3:09 PM said:
  
  Hi evegter. How did you manage to get access to shared mailboxes with MFA in Thunderbird? I can’t auth in IMAP with the usual \. Thank you!
  
  LikeLike
  
  Reply ↓
Shane on August 20, 2020 at 7:02 PM said:

This worked for IMAP (can fetch emails) , but is still failing for SMTP , is there some extra step to enable that on Office365 side?

LikeLike

Reply ↓
- Michel de Rooij on September 5, 2020 at 7:37 AM said:
  
  No. Did you check SMTP AUTH permissions was configured in the API permissions for the app?
  
  LikeLike
  
  Reply ↓
  - Branko S. on September 9, 2020 at 12:51 PM said:
    
    It appears that modifiying SmtpClientAuthenticationDisabled (which is blank by default) on user mailbox did the trick.
    Set-CASMailbox -SmtpClientAuthenticationDisabled $false
    After this thunderbird started to send emails.
    
    LikeLike
    
    Reply ↓
    - Michel de Rooij on September 9, 2020 at 2:00 PM said:
      
      Thanks for the heads-up.
      
      LikeLike
      
      Reply ↓
    - daniel on February 22, 2021 at 5:15 PM said:
      
      This is gold. Thank you so much, after one day of trying this feels amazing.
      
      LikeLike
      
      Reply ↓
Doug Siew on August 24, 2020 at 8:23 AM said:

Hi Michel,

I replaced the and in the URL below for getting admin consent:
https://login.microsoftonline.com//oauth2/authorize?client_id=&response_type=code&prompt=admin_consent

However, I got the following message:
Sorry, but we’re having trouble signing you in.
AADSTS90013: Invalid input received from the user.

I don’t think my organization will grant admin consent for this. I will not be able to contact my organization admin to do something like this.

Is there any other ways to make this work?

Thanks

LikeLike

Reply ↓
- Michel de Rooij on September 5, 2020 at 7:44 AM said:
  
  I suspect something was removed from your comment; alternative to admin consent URL would be:
  https://login.microsoftonline.com//adminconsent?client_id=
  
  Your organization need to have enabled 3rd party apps or have configured this app for you in order for it to allow the organization – or individuals – to use 3rd party apps like Thunderbird to access your data.
  
  LikeLike
  
  Reply ↓
aarem on October 14, 2020 at 2:36 AM said:

Hi, I wonder if you can help me with answering this question. Following your post and looking up other resources, I have set up an application that is able to allow me to get IMAP access (using OAUTH2) from Office 365. I also have it set up to allow me to send e-mail using SMTP (using OAUTH2), however my employer’s sysadmin says that he has disabled SMTP because he can not see how it can be enabled only for OAUTH2 and not also for basic authentication. (He says that SMTP auth became the favorite way for hackers to test credentials against our systems.) His concern is that he can’t just enable SMTP auth with Oauth, but thinks that he can only enable both. So, is it possible to have fine grained control such that SMTP authentication with OAUTH2 is enabled but not with basic AUTH. Thanks for answering if you know the anwer.

LikeLike

Reply ↓
- Michel de Rooij on October 14, 2020 at 2:35 PM said:
  
  Option 1 is to create a conditional access policy, blocking basic authentication for the mailboxassociated with the app (IMAP, POP and SMTP are considered ‘other clients’). https://docs.microsoft.com/en-us/azure/active-directory/conditional-access/block-legacy-authentication
  Option 2 is creating an AuthenticationPolicy in EXO, setting AllowBasicAuthSmtp to False (and likely for other protocols as well), and assign it to the (sending) mailbox associated with the app. https://docs.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/disable-basic-authentication-in-exchange-online
  
  LikeLike
  
  Reply ↓
Amanda Barbosa on January 26, 2021 at 1:37 PM said:

Hi Michael,
I have followed all the steps, but when I get to the Fetch emails step in Thunderbird, I receive a message that IMAP outlook.office365.com doesn’t support the selected authentication method. Do you know what could be?

LikeLike

Reply ↓
- Michel de Rooij on January 26, 2021 at 2:01 PM said:
  
  The selected authentication method hasn’t been configured (eg OAuth2) or has been disallowed (eg Basic Auth/Normal Password) by your admins. OAuth2 needs to be explicitly configured by your tenant admins (first part of article).
  
  LikeLike
  
  Reply ↓
Amar on February 3, 2021 at 4:05 PM said:

Hello Michel,

Is it necessary to register the thunder bird app in Azure ?

LikeLike

Reply ↓
- Michel de Rooij on February 3, 2021 at 4:43 PM said:
  
  If 1) basic auth has been disabled, and 2) users are not allowed to give consent to 3rd party apps for their data, yes.
  
  LikeLike
  
  Reply ↓
Luca on February 15, 2021 at 12:29 PM said:

Hello Michel,
i follow all steps, but still not working. THe system, SMTP, could send out the email.
I received a message: Access to server smtp.office365.com with username not success.
retry – insert a new password – cancel

LikeLike

Reply ↓
- Michel de Rooij on February 15, 2021 at 6:16 PM said:
  
  What is “the system”? When you configured Thunderbird with the smtp.office365.com host as SMTP endpoint, and provided the Thunderbird app – or any app withing to perform IMAP/SMTP using OAuth – with proper permissions, you should be OK, eg. “Read and write access to mailboxes via SMTP AUTH”. Also be advised that not all providers allow outbound traffic on port 25/465/587, which effectively blocks you from sending mail via SMTP from a client.
  
  LikeLike
  
  Reply ↓
- daniel on February 22, 2021 at 5:17 PM said:
  
  Hello, another user said that this command is necessary.
  Set-CASMailbox -SmtpClientAuthenticationDisabled $false
  https://eightwone.com/2020/07/01/configuring-exchange-account-with-imap-oauth2/#comment-271774
  I had the same issue that receiving emails worked, but sending was not working. After that, it works perfectly!
  
  LikeLike
  
  Reply ↓
  - Michel de Rooij on February 22, 2021 at 5:46 PM said:
    
    Good heads-up to add, thanks.
    
    LikeLike
    
    Reply ↓
aarem on May 9, 2021 at 9:42 PM said:

With basic AUTH disabled for all users, it is possible for an Exchange server to have SMTP switched on with OAuth2 at least for some users? We want SMTP with basic AUTH for all 2000 users disabled by default but SMTP with OAuth2 enabled for all or some users. How is this done? I am looking for detailed instructions. Thanks!

LikeLike

Reply ↓
- Michel de Rooij on May 9, 2021 at 10:42 PM said:
  
  On-premises, you cannot selectively disable basic auth for SMTP, i.e. through authentication policies in Exchange 2019. You can only disable Basic Authentication for some protocols using Exchange 2019, EAS, AutoDiscover, IMAP, MapiHttp, OAB, POP RPCHttp and EWS – see legacy authentication parameters for https://docs.microsoft.com/en-gb/powershell/module/exchange/new-authenticationpolicy
  
  LikeLike
  
  Reply ↓
  - aarem on May 9, 2021 at 11:13 PM said:
    
    Thanks, what about disabling basic auth for SMTP and switching modern oauth2.0 for SMTP on only (for specific mailboxes, perhaps). Can this be done? I am not interested in basic AUTH, but in SMTP only with modern oauth2.0.
    
    LikeLike
    
    Reply ↓
Oauth2Admin on May 24, 2021 at 10:43 AM said:

Hi Michel,

We have disabled the legacy auth in our mail environment, but now the users who had Thunderbird cannot sync their shared mailboxes, no issue with the personal accounts using Oauth2. Before disabling the legacy auth everything worked like a charm.

The app is registered in Azure, and everything looks fine. Any clue about what could be happening?

Thanks in advance

LikeLike

Reply ↓
- Michel de Rooij on May 24, 2021 at 6:38 PM said:
  
  No. Did you check the Azure AD > Monitoring > Sign-Ins section to see what goes on?
  
  LikeLike
  
  Reply ↓
  - Oauth2Admin on May 25, 2021 at 11:06 AM said:
    
    Thanks for answering, yes, in the sign-ins section I can see some interrupted requests while using TH, but just to provide more insights on the topic we’ve been able to configure the accounts in Thunderbird but in the username, we used the shared mailbox UPN (mailbox alias@tenant primary domain) that not match the actual shared mailbox address, using the mail address did not work as it does in Outlook.
    
    BTW, good and very helpful article. 😉
    
    LikeLike
    
    Reply ↓
    - pat on May 25, 2021 at 11:46 PM said:
      
      Thank You!!!! Your comment saved me some hours of worry.
      The error message are everything but helpful.
      
      For those who are facing similar problems, the IMAP error says:
      “User is authenticated but not connected.”
      
      LikeLike
      
      Reply ↓
      - J Roy on June 3, 2021 at 2:42 PM said:
        
        Did you change something else? When configuring shared mailboxes with mailbox-alias@tenant primary domain, I still have the message “User is authenticated but not connected”
        
        LikeLike
        
        Reply ↓
        
        Dominik Aigner on February 20, 2023 at 7:50 PM said:
        
        Same here! Found any solution?
        
        LikeLike
        
        Reply ↓
Yves on September 9, 2021 at 2:02 PM said:

Great Article, thank you MIchel. I have a test case in a test tenant where once you authorise the thunderbird app it has removed OWA and Outlook for all users…

LikeLike

Reply ↓
- Michel de Rooij on September 15, 2021 at 7:50 AM said:
  
  Doesn’t make sense to me.
  
  LikeLike
  
  Reply ↓
  - Yves on September 15, 2021 at 8:39 PM said:
    
    This was due to my test tenant expiring. I spun up a new tenant and re-tested and all OK. On another note my test Thunderbird app doesn’t out of the box sync the GAL or pull down a copy of the calendar. A few extra plugins required to get this to work “out of the box”. In my opinion I would suggest using Outlook or OWA instead. Thunderbird is a bit limited in its use case for modern auth and proper collaboration setup out of the box
    
    LikeLike
    
    Reply ↓
maathieumt22 on July 21, 2022 at 10:44 AM said:

still works well in 2022. Thanks!

LikeLike

Reply ↓
Jim on September 15, 2022 at 5:58 PM said:

Very nice article. I followed the steps, but am hitting a snag.

I am using a personal outlook.com account. Thunderbird presents the MSFT login screen, but gives me the error “You can’t sign in here with a personal account. Use your work or school account instead.”

The authentication link works in a browser if I change the tenant from “common” to my personal tenant ID.

Is there any way to configure things so the common tenant works?

LikeLike

Reply ↓