Microsoft 365 IMAP Setup with Azure and Microsoft Graph

NOTE: Feature support was released as of Patch 14-2.

Overview

This article provides detailed instructions for registering an application in the Azure Portal.

NOTE: These procedures apply to users using Microsoft 365, as Microsoft 365 is required for IMAP.

Procedure

1. Login to the Azure AD Portal and activate the PIM Role if applicable.

2. Navigate to the Azure Active Directory.

3. Under the Manage section on the left navigation menu, select App Registrations, then click New Registration.

   

4. Enter a name for the app. For example, this guide will use "CMiC Graph".

   

5. Under Who can use this application or access this API?, select the Accounts in this organizational directory only (CMiC only - Single tenant) radio button.

   

6. Click Register.

7. The newly created application will open. Under the Manage section on the left navigation menu, click on Authentication.

   

8. Under Advanced Settings > Allow Public Client Flows, set the toggle to "Yes", then click Save.

   

9. Under the Manage section of the left navigation menu, select Manifest.

   

10. Ensure “allowPublicClient” is set to true. Click Save if required.

    

11. Under the Manage section of the left navigation menu, select API Permissions. Any default permissions (e.g. User.Read) need to be removed by clicking the ... button and selecting the "Remove Permission" option.

    

12. Click Add a Permission.

13. In the Request API Permissions screen under the Microsoft APIs tab, select Microsoft Graph.

    

14. Click Delegate Permissions.

    

15. In the Select Permissions search field, type “mail” and expand the Mail section as shown in the screenshot below.

    

16. Check the Mail.ReadWrite and Mail.Send checkboxes. Then click the Add Permissions button, as shown in the above screenshot.

17. Click Grant Admin Consent for CMiC. A confirmation notification will appear to confirm the permission.

    

18. Verify that the “Granted for CMiC” status displays under the Status column for the configured permissions.

    

19. Navigate to the Azure Active Directory and select Enterprise Applications. Click on the newly created application. In this example, it's CMiC Graph.

    

20. Under the Manage section on the left navigation menu, click on Properties and ensure the Assignment Required toggle is set to "Yes". Click the Save button.

    

21. Under the Manage section on the left navigation menu, click on Users and Groups, then click Add user/group.

    

22. Add the account intended for use. In this case, it is “CMiC.Graph”.

    

23. Click Assign at the bottom of the screen.

24. Double check that the user does not require MFA or other conditional access that may block an unknown platform (it has been noticed Java is blocked as a valid platform).

25. This completes the Azure setup, but before continuing to CMiC, the Application (client) ID is needed. Go to Enterprise Applications and under the Manage section of the left navigation menu, click on All Applications (Preview). Search for the application and copy the Application ID, as shown in the screenshot below.

    

26. Next configure CMiC IMAP settings. There are two approaches, however in the application, one of the fields is hidden so this change would need to be done through SQL only.

    1. In CMiC, go to System Options > Web servers

       1. Server name: outlook.office365.com

       2. Port: 993

       3. User: <email account> (e.g. cmic.graph@cmic.ca)

       4. Password: <email password>

       5. Code1: Azure app client/application id

          1. In Azure graph_imap enterprise application

          2. Copy the application id

       6. Protocol: GRAPH. Prior to 15-2, the column may not be visible by default so check Lite Editor to add the hidden field. Otherwise, to set this value, the following SQL statement can be used:

          Copy

          update da.syswebservers set sws_protocol = 'GRAPH' where sws_url = 'outlook.office365.com' and sws_imap_flag = 'Y';

       7. IMAP Flag: Checked

    2. The following is an example to update application_id, protocol, and port in SQL:

       Copy

       update da.syswebservers set sws_code1 = '<application_id>', 
       sws_protocol = 'GRAPH', 
       sws_port = '993' where sws_url = 'outlook.office365.com' and sws_imap_flag = 'Y';

27. Update service command line arguments to only require cmicio.jar. For example:

    Copy

    -cp %ENV_HOME%\jsp\cmicio.jar cmic.cmicio.RunReadMailBox

    1. Service

       

    2. Task

       Note If a task is still being used, this is a good time to transition to a service.

       

28. Remove the mail.jar file from the D:\cm\v12\ENV_NAME\jsp folder.

    This is an old library that is no longer used and CMiC had discovered that it might be conflicting with the javax.mail.jar library that is used by the new MS Graph implementation. For this action, remove the D:\cm\v12\ENV_NAME\jsp\mail.jar file.

29. The weblogic of the environment where CMICIO service (or Scheduled Task) is running can cache the values of the CMiC IO configuration. To make sure that the new settings takes place, you will need to:

    1. Stop CMICIO service of the environment (or Scheduled Task).

    2. Restart the weblogic of the environment on the server where CMICIO service (or Scheduled Task) is running.

    3. Start CMICIO service of the environment (or Scheduled Task).

Troubleshooting

Below are following error which can be caused due to incorrect setup or possible security.

CMiC DBAs have a utility which can be used for testing to ensure that the workflow goes through, and it is able to access the mailbox and return the number of emails in the mailbox.

The utility is typically located on the CMiC app servers in D:\cm\ias\utility\cmicEmail\ and it is called IMAPTest.bat.

The latest version is September 2022 which contains the latest test. The utility can be downloaded from CMiC FTP under Public\cmicEmail_utility.

Testing of the Azure IMAP account can be done as:

IMAPTest.bat MS-Graph <CMIC_IO_EMAIL> <PASSWORD> <32-digits-application-id>

Output all the mailbox folder's information (name, unread, total, size):

IMAPTest.bat MS-Graph <CMIC_IO_EMAIL> <PASSWORD> <32-digits-application-id> -d

Move an email (found by its subject) from the inbox to the specified folder:

IMAPTest.bat MS-Graph <CMIC_IO_EMAIL> <PASSWORD> <32-digits-application-id> -f <mailbox folder> -e “email subject” -m

Example 1:

IMAPTest.bat MS-Graph sender@testServer.com mypassword 9c865bck-ckb5-4c2f-8405-167ba1fd4e0k

This utility will simply connect to the account using the MS-GRAPH protocol and retrieve the number of emails in it. If successful, it shows the value for unread emails, which means that the Azure side is configured correctly to read the mailbox.

Example of running the utility successfully:

Example 2:

IMAPTest.bat MS-Graph sender@testServer.com mypassword 9c865bck-ckb5-4c2f-8405-167ba1fd4e0k -d 

With the additional option, -d will display all the email folders with information as:

1. Number of unread emails

2. Total number of emails

3. Total size in bytes

Example of running the utility successfully:

Example 3:

IMAPTest.bat MS-Graph sender@testServer.com mypassword 9c865bck-ckb5-4c2f-8405-167ba1fd4e0k -e “Move from Inbox to Processed” -f processed -m

The additional options will move an email by subject from the inbox to the destination folder.

-e “<email subject>”

-f <destination folder>

-m is flag to indicate a move

Example of running the utility successfully:

AADSTS7000218: The request body must contain the following parameter

AADSTS7000218: The request body must contain the following parameter: "client_assertion" or "client_secret".

Problem may be caused by the fact that the application is created but has no permissions, or the "allows public client workflow" permission is enabled.

AADSTS65001: The user or administrator has not consented to use

AADSTS65001: The user or administrator has not consented to use the application with ID <app_id> named <app_name>. Send an interactive authorization request for this user and resource.

Problem may be caused by the fact that the application is available, but there are no API permissions available.

AADSTS50105: Your administrator has configured the application to block users

AADSTS50105: Your administrator has configured the application <app_name> (<app_id>) to block users unless they are specifically granted (assigned) access to the application. The signed in user, "{EmailHidden}", is blocked because they are not a direct member of a group with access, nor had access directly assigned by an administrator. Please contact your administrator to assign access to this application.

Problem may be caused by the application only allowing access from user/groups assigned to the application. Verify that the user is assigned.

404 – Accessing mailbox

Problem may be caused by the user's license. Check that the user's license is licensed for exchange online.

403 – ErrorAccessDenied - Accessing mailbox

{"error":{"code":"ErrorAccessDenied","message":"Access is denied. Check credentials and try again."}}

Problem may be caused by Azure application permissions. Check that the Azure application permissions are granted and correct for the mailbox (e.g. Mail.ReadWrite, Mail.Send).