[Tutorial] Connecting Frappe/ERPNext to Microsoft 365 mail services OAuth

[avc]

Hi:

To get connection between Frappe mail system and Microsoft365 mail services (formerly known as Office365) you will need:

Patience / faith

1. Requirements.

Update Frappe to v14.23.0 and above or v13.55.0 and above. Best option is most recent version, because some minor fixes are included.

You will need a frappe site running under https (or localhost on dev environments).

M365 account and admin privileges to manage OAuth

2. Microsoft 365 side:

On Azure AD admin you will need to create an App Registration, and configure here permissions, secrets, etc … Please, note that this kind of configuration could affect your data security.

2.a. App registration.

2.a.1 Access to your Azure Admin Portal

2.a.2 Use App registrations options

2.a.3 Create new registration. Don’t worry about URI redirects, we will configure it further.

2.a.4 Add permissions to the app registration. You will need IMAP.AccessAsUser.All and SMTP.Send from Microsoft Graph and IMAP.AccessAsApp from Office365 Exchange on line

After that, select each permission required and grant admin consent for them.

2.a.5 Copy the app client ID, is needed to configure Frappe side.

2.a.6 Create your secrets (keys). Copy the secret value (not the secret ID) (after this step this value will be not showed again). We will use this data further.

2.a.7 Get the OpenID configuration endpoint, we will need this in following steps.

On Frappe Side
2.b.1 Create a connected app (yoursite.com/app/connected-app) .

2.b.2 Copy the value of OpenID Configuration obtained before (2.a.7), and use “Get OpenID Configuration” button. this will get the endpoints urls. Now, fill Client ID (2.a.5) and secret value (2.a.6)

2.b.3 Add this scopes
https://outlook.office365.com/.default
offline_access

2.b.4 Copy the value “Redirect URI”

2.b.5 Use the Redirect URI value (2.b.4) and back to Registration App on M365 side, to add this url to authentication

2.b.6 Back on Frappe side connected app, use "Connect to “yourconnectedapp” button

Important: Use button “Connect” once logged on Frappe with the “final” user (not Administrator). At this point M365 will ask you for authorization.

2.b.7 Create an email account on Frappe and assign it to the “final” user.
Configure this way …

Important: Use button “Authorize API access” once logged on Frappe with the “final” user (not Administrator) .

Hope this helps!

(Note: This post will be edited with other contributions, probably there are a lot of scenarios and different configuration posibilities. Please, let me know if you find any wrong information)

OAuth for M365 is working thanks to the efforts of @revant_one, @ritwik, @ankush and others.

[rmeyer]

@avc could you share how you have configured the rest of the Email Account? When I enable “Use TLS” the validation fails, but when I disable it, I get a “TLS required” error when sending an email.

[avc]

Hi @rmeyer:

In my case, i use domain configuration, so email account has no comm options:

Theorically, account inherits from this.

[rmeyer]

The last bit, that was missing for me, was that I got this error message when trying to send an email:

5.7.139 Authentication unsuccessful, SmtpClientAuthentication is disabled for the Tenant. Visit Enable or disable SMTP AUTH in Exchange Online | Microsoft Learn for more information.

I was able to resolve this by enabling SMTP Auth as described in the link above.

Apparently this is still required, even when using OAuth:

The SMTP AUTH protocol is used for SMTP client email submissions, typically on TCP port 587. SMTP AUTH supports modern authentication (Modern Auth) through OAuth in addition to basic authentication.

[saurabhn]

Firstly, thanks a ton. This is the first guide that seems to make the functionality work!
I am able to fetch now for a 365 user.

My question is how do we use this to configure emails like sales (sales@domain.com), job which don’t directly map to particular ERPNext users. Do we just create fake users for them in ERPNext or is there a way to may those email to some other user from sales team?

Thanks agiain for your help

[rmeyer]

It should be no problem to configure generic emails. Try configuring the Email Account as follows:

1. Email Address: “sales@example.com”
2. Connected User: “system-manager@example.com”
3. Make sure you’re logged out from microsoft with your personal account
4. Click “Authorize API Access” and log into microsoft as sales@example.com

Once the Email Account is authenticated, you can grant any user access to this email account via their User DocType.

[lmmena2]

I am configuring everything the same, but I get this error when I try to connect. Do you know what could be happening?

[muslimaziran]

This is brilliant @avc. Thank you so much.

I was able to follow thru the steps and don’t face any issues till I reach the state where I have setup a new email account for a person based on OAuth. Here it gives me the error Invalid Credentials, Please check your email login credentials.

I cannot figure out what credentials is it referring to.

Please guide.

[muslimaziran]

[avc]

Hi @muslimaziran:

Is this mail account linked to a connected app?

[muslimaziran]

Yes,
so first I created a M365 user with the email address that I am interested to use as a default sending email in ERPNext. Then I created a user with the same email address in ERPNext. On logging in as this user I went to the conneted app and used the Connect to M365 (name of app). It asked me to log into the M365 account, I successfully logged into the account.

Then I created the email address for the same user but it gives the above error.

[revant_one]

@avc

i use domain configuration

Try creating Email Domain and inherit from it into Email Account.

[thomasr]

Thanks for this in-depth tutorial! It sums up perfectly what I found out by searching multiple threads and issues. The official documentation on this topic is basically useless or not existing! Maybe we can extend it a little further and place it in the official frappe docs?

Anyways, I still have issues with the integration of emails with Office365 and ERPnext/frappe.

We use the Security Defaults provided by Microsoft, which state to “Block legacy authentication methods, such as SMTP Auth”… see: https://learn.microsoft.com/en-us/azure/active-directory/fundamentals/concept-fundamentals-security-defaults#block-legacy-authentication-protocols

Did anybody get the email sending to work with Security Defaults enabled? Or am I required to use a Mail Connector for sending? see https://learn.microsoft.com/en-us/exchange/mail-flow-best-practices/how-to-set-up-a-multifunction-device-or-application-to-send-email-using-microsoft-365-or-office-365#option-3-configure-a-connector-to-send-mail-using-microsoft-365-or-office-365-smtp-relay

Thanks!

[revant_one]

Is it this step discussed here? [Tutorial] Connecting Frappe/ERPNext to Microsoft 365 mail services OAuth - #4 by rmeyer

[avc]

Hi:

I was able to sending through SMTP even without OAuth … it’s still working disabling Security Defaults and probably it will works for a long time …)

Also is possible to activate/deactivate SMTPAuth on certain accounts (via Powershell)

Enable or disable SMTP AUTH in Exchange Online

Anyway … STMPAuth isn’t needed since OAuth was implemented …
Hope this helps.

[thomasr]

Nope, that was not the issue.
I created a new connected app and now its working.
I followed the tutorial step by step. Maybe i missed something in the first run.

Great tutorial. Please move it over to the official docs for Connected Apps in Frappe

[Khushal]

@avc I follow all your steps and my incoming email is working completely fine but when I enable outgoing I am getting this error I can’t find where it was gone wrong

[avc]

Hi:

Check the permissions of your M365 user.
Can use SMTP?

Hope this helps.

[Khushal]

I did OAuth for Office 365 and after It didn’t required to enable or disable SMTP AUTH but when I enable outgoing i got this error

[avc]

Hi:

Have you checked this?

Enable or disable SMTP AUTH in Exchange Online