Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

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. Choose the middle option "https://login.live.com/oauth20_desktop.srf", and leave "Custom redirect URIs" at the default (blank). 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. Go to the "System Settings" tab of the plugin and 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. Configure the staff records. Load a staff member via System Settings → Staff Configuration → Staff Maintenance. Enter the staff members Office 365 username and password in the "SMTP Username" and "SMTP Password" fields respectively. If you want the use to appear to be sending email from a different account (i.e. "contactus@jiwa.com.au" or "accounts@jiwa.com.au"), then enter the desired address and display name in the "Address" and "Display Name" fields. Save.

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 not currently supported by the "Email - Configuration Microsoft Graph REST API" plugin, so we must ensure that this is disabled on user accounts in Office 365. Follow the steps below to set these permissions and disable 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 disable 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 "Disable" link (Note: the screen shot below shows the right hand side link as "Enable" because multi-factor authentication is already disabled for this particular user).

Disable!

Again, the screenshot above shows the "Disable" link as "Enable" because this user already has multi-factor authentication switched off. You want to ensure that multi-factor authentication is DISABLED for all users that email out of Jiwa.


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.





  • No labels