Microsoft Email OAuth
This guide helps in authenticating an outlook email account in frappe.
1. On Azure portal, search for and select Azure Active Directory .
2. Under Manage , select App registrations > New registration .
3. Go to your Frappe/ERPNext instance and create a
New Connected App
and save it (just enter the name and save) and copy the Redirect URI.
4. Back to the Azure Portal, enter the respective details (app name, account type) and add the redirect uri from Frappe instance and select the platform as “Web”.
To know more about the account types, visit: https://learn.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#register-an-application
5. Click on Register and you’ll be redirected to your created app and save your Application ID - it’s your Client ID on Connected App in Frappe instance
6. Head over to API Permission section in your app and add Microsoft Graph permissions
7. Select Delegated Permissions for IMAP, SMTP and offline_access (for generating refresh token)
8. Click on Add permissions and you should have all these permissions.
9. Head over to Certificates & Secrets to create a Client Secret
Add description and click on add to see a newly generated client secret.
Copy over the Value - it’s the Client Secret in Connected App on your Frappe instance.
10. On your Connected App add the Client ID and Client Secret from your newly registered app on Azure and add Scopes, Authorization and Token URI’s.
For Scopes- these must be added (assuming IMAP & SMTP are being used):
-
offline_access
The correct endpoints for your app can be found over in your Azure portal over here:
11. Save the connected app and click on the “ Connect to {your connected app name} ” button on top right which should start the Oauth flow for Microsoft.
Make sure the email account you’re authorizing is going to be the same as the one you’re going to add in frappe.
12. If everything goes as planned, you’ll be redirected back to your Connected App page and should be able to see Token Cache connected to your connected app, head over to your created token cache to check if you have both refresh and access token.
13. Head over to Email Account doctype and create a new Email Account. And select the method as Oauth and add your connected app and user which has created the token cache and set up your email account as usual.
You can check the settings for outlook servers over here: https://support.microsoft.com/en-us/office/pop-imap-and-smtp-settings-8361e398-8af4-4e97-b147-6c6c4ac95353
NOTE: Microsoft restricts sending from any other email address other than the one which authenticated it. For that you can check these 2 options in the email account document itself
Please visit Microsoft’s official documentation for any Additional Info: https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth
Service Principal Authentication
Email Accounts require access as a User. This disallowed the use of Shared Mailboxes dedicated to Frappe, as Full Access permissions would need to be granted to the user signing into Frappe.
This feature lets Frappe authenticate itself to e.g. Exchange Online, so it can send and receive emails from the Shared Mailbox, without having to delegate Full Access permissions to each user that accesses Frappe.
If you wish to authenticate using this method, there's a checkbox available in
Email Account
