Email - Configuration Microsoft Graph REST API
- Scott Pearce
- Monica Holliday
- Mike Sheen
- Julie Hanlon
The "Email - Configuration Microsoft Graph REST API" plugin uses the most up-to-date technology to send emails from Jiwa. To use this plugin you must have an Office 365 subscription as Office 365 is what the plugin connects to in order to send email from users. A Microsoft Azure subscription is also required - but you get one of these when you create your Office 365 subscription - just use your Office 365 administrator credentials to log in to Microsoft Azure. There are three aspects to setting up this plugin - registering and configuring an "App" in the Microsoft Azure portal, configuring Jiwa and some values in the plugin itself, and setting some permissions on users mail accounts in Office 365 Admin.
App Registration
The "Email - Configuration Microsoft Graph REST API" plugin acts as an "App" as far as Microsoft Azure is concerned. We must register this app with your Microsoft Azure subscription to allow users to be properly authenticated by Azure (and therefore Office 365), and to control what the app can and cannot do (i.e. "permissions"). Follow the steps below to register the "Email - Configuration Microsoft Graph REST API" plugin acts as an app in Microsoft Azure:
1. Log in to your Microsoft Azure subscription via the Azure portal.
2. Search for "App registrations"
3. Click on the "New registration" button, and enter a name for the app (i.e. "Jiwa Emailing"). Leave everything else at default and click the "Register" button.
4. You will now be taken to the "Overview" page for the new App. Go to the "Authentication" section and click on "Add a platform":
5. From the list of platforms, choose "Mobile and desktop applications":
6. After clicking on "Mobile and desktop applications" you will be asked to choose a "Redirect URI". This tells the app where it should go when it needs to authenticate a user. Untick the default options and enter “http://localhost” in the "Custom redirect URIs" section. Click the "Configure" button.
7. Enable "Allow public client flows". Save.
8. Go to the "API Permissions" section and then click on the "Add a permission" button:
9. From the list of APIs, choose "Microsoft Graph":
10. Choose "Delegated permissions":
11. Search for "Mail", expand the "Mail" section, and tick "Mail.ReadWrite", "Mail.ReadWrite.Shared", "Mail.Send", and "Mail.Send.Shared". Then click the "Add permssions" button:
12. You will now be back at the main "API Permissions" page. Click on the "Grant admin consent for X" button (where X is the name of your organisation), and then click "Yes" to confirm.
13. Go back to the "Overview" section for the new app, and copy the "Application (client) ID" and "Directory (tenant) ID" into notepad or similar:
Jiwa & Plugin Configuration
Now that the app has been registered and configured in Microsoft Azure, we can configure Jiwa and the "Email - Configuration Microsoft Graph REST API" plugin.
1. In Jiwa, go to System Settings → Plugins → Plugin Maintenance, and load the "Email - Configuration Microsoft Graph REST API" plugin. Check the Enabled checkbox and save.
2. Go to the "System Configuration" form an on the "Email - Configuration Microsoft Graph REST API" tab paste the "Application (client) ID" value (noted down from the previous section step 13) into the "ClientID" setting contents and the "Directory (tenant) ID" value (also noted down from the previous section step 13) into the "TenantID" setting contents.
Save.
2. Load the staff member via System Settings → Staff Configuration → Staff Maintenance - on the Main tab, enter the Email address and Display Name - these will be the default used when sending emails.
If you are going to be emailing from services or applications which cannot interact with the user, then you must check the NonInteractive setting on the Custom Fields tab, AND you must also provide the Office365 credentials on the Main tab as the Username and Password.
NonInteractive accounts must have Multifactor Authentication disabled.
You do not need to set these credentials if the NonInteractive field is left unchecked, and those accounts are able to use Multifactor Authentication.
Alternate From Address
If you enter a value in the "Address" field that is not blank and differs from what is in the "SMTP Username" field, then that email address (the one in the "Address" field must also be a valid email account in Office 365, and must also be configured in Office 365 Admin to allow this user (the one in the "SMTP Username" field) to "Read and manage", "Send as", and "Send on behalf" . See the section below for setting such Office 365 permissions.
Office 365 Permissions
Normally, out-of-the-box, Office 365 Exchange accounts will be able to email out of Jiwa OK at this point. However, if alternate from addresses are to be used (i.e. my email address is "scottp@jiwa.com.au" but I want emails out of Jiwa to appear to be from "accounts@jiwa.com.au"), then there are some permissions that need to be set. If users do not send email using an alternate "From" address , then this section can be skipped.
1. Login to your Office 365 account via https://www.office.com/ as a user that has administrative privileges.
2. Go to the Admin section.
3. On the left hand menu, expand the "Users" section, and choose "Active Users". From the list of users click on the entry for the user that you want to be able to send on behalf of, then click the "Mail" section for that user.
4. Click on the "Read and manage permissions (0)" link and add the user(s) that you want to be able to send as this email account. Save changes. Do the same for the "Send as permissions (0)" link and "Send on behalf of permissions" link.
Multi-factor authentication is supported by the "Email - Configuration Microsoft Graph REST API" plugin, so you should enable this on user accounts in Office 365. Follow the steps below to set these permissions and enable multi-factor authentication.
Multifactor Authentication
Multi-factor authentication is a mechanism that adds an extra layer of security to an account. Every time a user logins in, they must also pass a second challenge such as entering a one-time pass-code sent to a mobile phone or generated by an authenticator app.
1. Login to your Office 365 account via https://www.office.com/ as a user that has administrative privileges.
2. Go to the Admin section.
3. On the left hand menu, expand the "Users" section, and choose "Active Users". From the list of users click on the entry for the user that you want enable multi-factor authentication. Scroll to the bottom of the "Account" section and click on the "Manage muli-factor authentication" link.
4. You will now be taken to a separate page. You must now select the user again, and then on the right hand side click the "Enable" link.
Testing
To test that emailing has been configured correctly log in to Jiwa. If you are already logged in to Jiwa, log out and back in to ensure that the "Email - Configuration Microsoft Graph REST API" plugin has it's new "ClientID" and "TenantID" system setting values applied. Go to System Settings → Email → Email Maintenance and create a new email record. The "From" address should already be correctly populated as per your Staff Maintenance record. Enter a "To" address, Enter a "Subject" and "Body" and ensure that the "Status" is set to "Sent". Save. No error message should be given. Check the inbox of the "To" address email account and/or the sent items of the "From" address email account to confirm that the email message was received/sent.
Latest plugin
Steps to deploy plugin.
| 
|
|---|