Setting up OAuth2 with Outlook

In this post, I will show you how to set up an Outlook OAuth2 application to generate credentials for IMAP and SMTP that you can then use with EmailEngine or any other email client or library for OAuth2.

EmailEngine has native support for Gmail and Outlook (Hotmail.com, MS365, and such) OAuth2 accounts. How to use OAuth2 with Gmail has been covered before. In this post, we will look at Outlook.

Even though this post describes setting up OAuth2 with EmailEngine, the same applies to any other IMAP/SMTP client as well, where you would need to provide the OAuth2 credentials in order for the mail application/library to work.

To start, we need to navigate to and log in to Azure Active Directory. Just as with Gmail, we need to create an application that will manage the credentials, so open the "App registrations" page and hit the "New registration" button.

To set up the application there are three values to fill. First is the application name. Whatever you choose here will be shown later to the users in the authorization form so make it something that is easy to understand.

Then we need to select which kind of account types will we support. The easiest would be to go with "Personal Microsoft accounts only" as this does not need any kind of validation at all but the downside is that you pretty much are stuck with hotmail.com addresses only. Great to test things out, not so good for production apps.

Finally, you have to set the application callback URL. This is basically your EmailEngine's base URL prefixed by "/oauth". Beware though that you either have to provide a valid HTTPS URL or alternatively a "http://localhost" URL. You can not use the localhost IP address, that is "http://127.0.0.1", as for whatever reason it is not allowed.

Now we have our application and we can already get the first required identifier, the "Application ID" that we later need to set up OAuth2 support in EmailEngine.

To continue setting up the application, click on the "API permissions" menu link.

Here on the API permissions page, we can set up the permissions our application requires. By default, there's only "User.Read". We can't do much with this permission, so click on the "Add a permission" button to add the rest.

All the permissions we need can be found from the default "Microsoft Graph" section, so click on the large button to continue.

Depending on your account type, you might also be presented with a choice between delegated and application permissions. Choose the delegated option.

First, search for "IMAP" and mark the "Imap.AccessAsUser.All" checkbox. This is needed to read emails from an IMAP account.

Next, do the same with SMTP. This is needed to send emails via SMTP.

And finally, search for and mark the "offline_access" permission. This gives us the capability to refresh expired access tokens. That's it for now, click on the "Add permissions" button to continue.

We should see all the permissions we required listed on the overview page. If everything seems fine then we are done with this topic and can continue. Click on the Certificates & secrets menu link.

This is the main part, where we can generate a client secret needed by EmailEngine. Click on the "New client secret" button to create one.

Not much to see here, set some kind of name for the new secret and choose an expiration time you're fine with.

Once the credentials are created we should see the actual secret value. Make sure to copy this value (the one in the "Value" box) as it's not shown anymore once you close this page. This is the "Client Secret" for EmailEngine.

We have all the values we need, so we can start configuring EmailEngine to support Outlook OAuht2 authentication. Navigate to Configuration->OAuth2 and then select the Outlook tab.

Use the Application Id and Client secret values you got from the Azure portal. The redirect URL must be exactly the same one you used when registering the application.

"Account types" value depends on the type of accounts your application supports. For example, the default "consumers" is for Microsoft accounts (e.g., Hotmail). "organizations" allows MS365 accounts, and "common" supports both. If you want to support a specific organization only, you can use the Directory ID value for that organization like "f8cdef31-a31e-4b4a-93e4-5f571e91255a".

Also, make sure to mark the "Enable OAuth2 support for Outlook" checkbox or the Outlook option does not become available in account setup forms.

Now we can open the accounts page and click on the "Add an account" button. Set some name and account ID values and click on the "Continue" button to do so.

Select "Outlook" as the account type to add.

If you are not yet logged in to Outlook you will have to do so. Once you are authenticated you will be displayed the following, slightly scary-looking form. Don't be afraid and click on "Yes". If you are using MS365 accounts you might see a different page, for example, a warning that the admin of the domain has not accepted your application. Getting these things correct is out of scope for the current blog post.

That's pretty much it then. If all succeeded the account should be listed and should switch into the"connected" state in a moment.

IMAP and SMTP permissions

If you are managing an MS365 organization and EmailEngine cannot connect to IMAP or SMTP of the email accounts you manage, you might need to enable support for these protocols manually. Navigate to https://admin.microsoft.com/ and enable IMAP and SMTP, as shown in the image below.