Sending email via SMTP in Business Central (online and on-premise)

It’s not a secret that Microsoft is forcing OAuth authentication for several products, including Exchange Online and Business Central Online. Over the last couple of days, I got multiple requests from partners who are now struggling with configuring SMTP in Business Central for Exchange Online.

Let me start with reassuring you: Exchange Online still supports SMTP with basic authentication! It is not required to move to OAuth. It’s highly recommend though, but Business Central does currently not support all scenarios.

But wait… are you sure about that? Yes, I am! Here is a quote from the official documentation:

SMTP AUTH will still be available when Basic authentication is permanently disabled on October 1, 2022. The reason SMTP will still be available is that many multi-function devices such as printers and scanners can’t be updated to use modern authentication. However, we strongly encourage customers to move away from using Basic authentication with SMTP AUTH when possible. Other options for sending authenticated mail include using alternative protocols, such as the Microsoft Graph API.

The list of devices that can’t be updated to use modern authentication can also be expanded with a list of applications that don’t support modern authentication. Unfortunately, Business Central on-premise is on that list. Even when you are using the latest version. Even Business Central Online does not support all scenarios for SMTP with OAuth authentication.

I assume you know how to create email accounts in Business Central. If not, then please read this article first.

Business Central online

Let’s first see what we can do with Business Central Online. The SMTP Account card looks like:

Sending an email with these settings works fine. As long as you send emails in from a user session, or from a background session that was started under the same user account. That includes API sessions when using user delegation. The access token that is used to authenticate against Exchange Online is using delegated permissions. As a result, sending email from API sessions that are using client credentials flow (aka service-to-service authentication) do not support sending emails.

If you have an external application that calls Business Central APIs by using service-to-service authentication, then the API session will fail to send emails using the SMTP account.

The only solution for this is to fall back to basic authentication. See below how that works.

Business Central on-premise

Setting up SMTP with OAuth for on on-prem environment can be really cumbersome. You need to create an Azure app registration with specific permissions. After setting up Business Central the configuration is almost carved in stone. If something fails, e.g. the permissions were not correct, then there is no way to correct the permissions. Business Central uses refresh tokens to get a new access token and that simply doesn’t allow you to get a new access token with updated permissions. The only option would then be to recreate the Azure app registration and run page 6300 in the browser to enter the new app registration details.

So, what are the correct Azure app registration details for SMTP?

The official documentation can be found here: https://learn.microsoft.com/en-us/dynamics365/business-central/admin-how-setup-email#setting-up-email-for-business-central-on-premises. Because pictures are worth a thousand words, here is the complete process.

The first step is to open page 6300 “Azure AD App Setup Wizard” in Business Central. This page automatically opens when you set up SMTP for the first time. However, there is no action to open this page again if you need to enter new details. That’s a problem, for example when the secret expires you need to update it. And then you search left, right and center in Business Central, but you don’t find a way to update the secret. The only option is to run page 6300 directly by adding ?page=6300 to the URL.

The wizard page looks like this (after clicking on Next on the first page):

Make a copy of the Reply URL, you will need it in the next step. Open the Azure Portal and navigate to Azure Active Directory and then to App registrations. Here is a direct link: https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps.

Click on New registration. Give your app a name, e.g. Business Central on-premise.

Under Supported account types select the second option: Accounts in any organizational directory (Any Azure AD directory – Multitenant). It is very important to select this option, otherwise it will not work!

Under Redirect URI (optional) select Web as platform and paste the copied Reply URL from the wizard page in Business Central.

Click on Register and in the next page copy the Application (client) ID. Paste this value in the Application ID field in Business Central.

Then click on Certificates & secrets in the left menu. Click on New client secret, select an expiration period and then click on Add.

Copy the value and paste it in the Key field in the wizard in Business Central.

Finally, you need to set the permissions. Click on API permissions in the left menu. The list will already contain one permission: User.Read for Microsoft Graph.

Click on Add a permission and then on Microsoft Graph and then on Delegated permissions. We need to add the following permissions:

• offline_access
• openid
• SMTP.Send

The best way is to use the search box. Type in the permission name and then select the checkbox. Here is an example with the SMTP.Send permission:

Click on Add permissions to add the selected permissions to the list of configured permissions. Now we need to one other permission:

• Office 365 Exchange Online / User.Read

This permission is a little bit hard to find. Click on Add a permission. Then go to APIs my organization uses and type in the search box Office 365 Exchange Online.

Select this API and then click on Delegated permissions. Search for the User.Read permission, select it and click on Add permissions. The list of permissions should now look like:

That’s it! The Azure app registration is ready. In the wizard in Business Central click on Next and then Finish.

The final step in Business Central is to test the SMTP mail account. This will trigger the process to request an OAuth access token. Because it is the first time, during this process you will be asked to give consent to the requested permissions. This will happen in a window that looks like:

Now we have Business Central on-premise configured in exactly the same way as Business Central online. You can send emails using SMTP from a user session or a background session that runs under the user account. But sending emails from an API session that is using service-to-service authentication is not possible. So that brings us to the final part of this blog post.

By the way, for security reasons I’d strongly recommend to block user access to page 6300 or 6301. If someone runs them in the web client then he could just get his hands on the secret. Below is a screenshot of page 6301:

Setting up SMTP with basic authentication

According to the documentation, basic authentication will still be available for SMTP. However, that does not mean it will work out of the box. There are two potential issues that we may need to solve.

Enabling SMTP basic authentication

The first issue is that Microsoft may have disabled basic authentication for SMTP for a Exchange online environment. This happens if they didn’t detect any usage of basic authentication. But we can turn it back on. This can be done for the whole organization, so all mail accounts can use it again. Or it can be switched on per individual mail account, which overrides the organization-wide setting. For more information, see this blog post under the FAQ section: https://techcommunity.microsoft.com/t5/exchange-team-blog/basic-authentication-and-exchange-online-september-2021-update/ba-p/2772210

To re-enable SMTP basic authentication follow the steps here: https://learn.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission. It contains the steps for both enabling it for the whole organization or for an individual mailbox.

Working around multi-factor authentication

The second issue is called multi-factor authentication (MFA). If a user account has MFA enabled (which should be the case) then basic authentication is not going to work. The reason is that MFA requires user interaction, and basic authentication doesn’t support that.

The solution for this is to use a so-called app password. This is an option that allows creating a single password that can only be used for restricted scenarios. Read more about this feature and how to use it in this article: https://learn.microsoft.com/en-us/azure/active-directory/authentication/howto-mfa-app-passwords. It may need to be enabled, this article also explains how that works.

A step-by-step instruction to create an app password can be found here: https://support.microsoft.com/en-us/account-billing/create-app-passwords-from-the-security-info-preview-page-d8bc744a-ce3f-4d4d-89c9-eb38ab9d4137.

After creating the app password you can use it in Business Central. On the SMTP Email Account page, select Basic in the Authentication field and paste the app password in the password field.

With this configuration, it will also be possible to send emails from sessions that are running under a different user account, including API sessions that are using service-to-service authentication!

Hope this saves you a lot of time!

PS. I believe the support of OAuth for SMTP can be improved in several ways. Using basic authentication is not recommended, but we have no other option at this moment for API sessions using service-to-service authentication. And I believe that the code behind should be using Microsoft Graph instead of the old Exchange APIs. Also the way how OAuth is implemented in Business Central (not using v2.0!) should be updated.

Original Post https://www.kauffmann.nl/2022/09/29/sending-email-via-smtp-in-business-central-online-and-on-premise/