Introduction
MoxiEngage integrates directly with your brokerage’s Microsoft 365 (formerly Office 365) account to provide your agents and support staff with consistent and convenient access to their information, while eliminating any need to enter the same information multiple times.
Don’t panic! This setup has been completed by hundreds of individuals with no previous experience in setting up email accounts and/or credentials. This document includes screenshots of of the entire process, step-by-step. You got this!
Use the links below to jump to a particular MoxiEngage integration set-up step:
Register a MoxiEngage Application as an API Client
Submit Credentials to MoxiEngage
If you have questions or concerns, please check out our Tips and Further Info!
Overview
MoxiEngage uses Modern Authentication with an impersonation service account through the Exchange Web Services (EWS) Managed API to synchronize data and perform actions on behalf of individual users. Each MoxiEngage user account has an email address that corresponds to a mailbox on your Microsoft 365 account. All integration actions are performed within the context of a single given mailbox. MoxiEngage never requires administrative access to your Microsoft 365 account.
Contacts
MoxiEngage continually synchronizes a user’s contacts and contact details with the Microsoft 365 Exchange mailbox. Contacts created in Microsoft 365 will appear in MoxiEngage. Contacts created in MoxiEngage are synchronized back to the Microsoft 365 mailbox.
Calendar
MoxiEngage displays the user’s calendar events and appointments. Calendar events and appointments can also be added through MoxiEngage and are synchronized to the Microsoft 365 mailbox.
MoxiEngage sends certain email messages through user’s mailbox. These email messages will appear in the Sent mail folder and will be delivered to the recipient from the mailbox just as if the user had sent the email from Microsoft 365 directly. MoxiEngage does not synchronize or inspect incoming email messages.
Information Gathering
To enable configuration of the MoxiEngage integration, we will need to gather some key information and credentials from you, including the service account credentials, Client ID, and Tenant ID obtained by following the steps in the Microsoft 365 Setup Instructions for Administrators section of this document.
Next Steps
Verification of Credentials
MoxiWorks staff will begin the next step of the integration process. We will test the credentials you provided to verify that the service account is able to connect to your email service using Modern Authentication and perform a synchronization for the test email address you supplied.
Outcome: Credentials Cannot be Verified
If your entered credentials cannot be verified, we will contact you. Your email administrator will need to resolve the issue and then you will provide us with the updated information.
Outcome: Credentials are Verified Successfully
If your credentials are verified successfully, we will store the credentials securely. Congratulations! This is a key milestone that enables us to continue the process of getting MoxiEngage enabled for your brokerage.
Security
MoxiWorks requires the use of a single username/mailbox on your Microsoft 365 instance, configured as a service account with the Application Impersonation role. All interactions between the MoxiWorks system and your user’s mailboxes happens through this designated impersonation account and delegation access to the EWS Managed API. MoxiEngage never requires administrative access to your Microsoft 365 instance.
Network Access
MoxiWorks systems communicate directly with Microsoft 365 servers over secure HTTPS/SSL connections.
Managing Shared Secrets and Credentials
For automated access, MoxiWorks makes use of methods native to our configuration management software. Credentials are stored in encrypted objects accessible only to servers with the relevant service role and environment. These credentials are pulled and decrypted during software deployment. Server identity is validated via pre-shared public/private key. Credentials are managed through a commercial password manager and any non-automated access is limited to the MoxiWorks Technical Operations team and, with customer approval, limited support personnel on an as-needed basis. See also:
https://docs.chef.io/secrets.html#encrypt-a-data-bag-item
https://www.lastpass.com/en/enterprise
Communications Policy for Security Breaches
In the unlikely event of a security breach where client data such as account credentials for registrar management, impersonation credentials, and the like may have been compromised, MoxiWorks Technical Operations and/or Account Management staff will notify affected clients. If the client is aware of a potential security breach, they should notify MoxiWorks immediately so that we may contain and mitigate potential risk in a timely manner. In either case, a change to Impersonation account credentials will be coordinated between both parties.
Microsoft 365 Setup Instructions for Administrators
A client application must also be registered and configured with delegation access to the Exchange Web Services (EWS) Managed API to support Modern Authentication.
Microsoft 365 menu structure and user interface is subject to change. Steps provided in this document were performed from a computer running Windows 10 Pro against a Microsoft 365 instance created in July 2021. If you are running an on-premises installation of Exchange Server, the actual steps required to accomplish these tasks may be different than those described in this document.
The instructions provided in this guide are not intended to provide security advice for configuring your Microsoft 365 instance. The documented steps represent the most direct approach available at the time of this writing to achieve the necessary access required by MoxiWorks products. Other methods of configuration may be available.
Register the MoxiEngage Application as an API Client
Login to your Azure Active Directory Admin Center.
Click on the double chevron in the top left corner of the screen to expand the written menu.
Click on the “Azure Active Directory” option in the menu.
From the Azure Active Directory Dashboard for your Microsoft 365 instance, click on the “App Registrations” menu option under the “Manage” grouping.
Click on the “New registration” link.
Enter a name for the MoxiWorks client application (e.g., MoxiEngage).
Indicate the type of Microsoft 365 account that will be using MoxiEngage. In most instances, the Single Tenant default selection will be correct.
The Redirect URI settings are optional. No changes are needed.
Click on the “Register” button.
Observe the notification that your application was created successfully.
Locate the value next to the “Application (client) ID” label, then click on the “Copy to clipboard” button (only visible when you hover over the value).
Paste the value to a text file for reference. You will need to provide this value to MoxiWorks as your Client ID.
Locate the value next to the “Directory (tenant) ID” label, then click on the “Copy to clipboard” button (only visible when you hover over the value).
Paste the value to a text file for reference. You will need to provide this value to MoxiWorks as your Tenant ID.
Click on the “API permissions” option under the “Manage” grouping of the menu.
Click on the double chevron to collapse the side menu.
Note: The “User.Read” permission for the “Microsoft Graph” API may be listed in the “Configured permissions” list. This permission does not provide sufficient permissions for MoxiEngage to perform core functionality.
Click on the “Add a permission” link.
Click on “APIs my organization uses” tab to change the view of available APIs.
Type “Office” in the Search box to filter the API list.
Click on the “Office 365 Exchange Online” API name.
Click on the button with “Application permissions” as the title.
Locate the “Other permissions” item under the “Select permissions” area of the screen, then click to expand the permission group.
Check the box next to the “full_access_as_app” permission under the “Others” permission group.
Click on the “Add permissions” button.
Observe the confirmation message and note that the selected permission has been added to the “Configured permissions” list.
Click on the link to “Grant admin consent for” your domain.
Click on the “Yes” button to confirm.
Observe the confirmation message(s) and the change in permission status indicating that consent is “Granted for” your domain.
Click on the “Authentication” option under the “Manage” grouping of the menu.
Scroll down to “Advance settings”, locate the “Allow public client flows” setting and change the setting to “Yes”.
Observe the confirmation message and the change in setting is “Yes”.
Click on the “Certificates & Secrets” option under the “Manage” grouping of the menu.
Click “New client secret”.
Insert a description “Engage access” or anything you prefer.
In the Expires dropdown menu select a date you would like to grant access to Engage. Please record this date as you will need this information when submitting your credentials. We recommend a minimum of 2 years.
Caution: We will require a new client secret to be created when this secret expires. If that is not provided it may result in an interruption of service for MoxiEngage.
Find the secret Value (not Secret ID) you just created in the list. Click the icon to copy the secret into a location to be submitted later. Be sure you are copying the Value and not the Secret ID.
Caution: Client secret values can only be viewed once at creation. Be sure to save the secret when created before leaving this page.
Provide to MoxiWorks the values you have saved for the registered application Client ID (step 11), Tenant ID (step 13), the client secret (step 36), and a standard (non-administrator) user account that may be used for testing the impersonation setup.
Submit Credentials to MoxiEngage
Once the above process is completed, please submit your credentials to us through this Cognito form
Tips and Further Information
- Why is this process necessary for Engage to function for our agents?
- Engage functions through a sync between itself and an agent’s email. Without an email to sync to Engage cannot work.
- Engage can sync to an office-provided MS365 or Google Workspace account, provided that your office completes the Integration Process.
- Integration process can only be completed by someone with admin credentials to the office email tenant.
- Once you’ve completed the process you must submit those credentials to us here:
https://www.cognitoforms.com/MoxiWorks2/moxiworksrealogyengagecredentialsform
- If you do not have an office provided email or prefer not to do this process for any reason, your agents will always have the option to sync using a Free Gmail account. No further action is required by your office in this case.
- Notes about known issues and what to do:
- 3rd Party Provided Email - Offices with email accounts purchased through third party companies such as Go-Daddy may not be able to complete process due to limitations they place on admin access. Your agents will still be able to sync with Free Gmail.
- Access / Permissions - If you do not have admin privileges to your email tenant you must escalate to someone who does or reach out to your email provider. Moxi cannot assist you with your permissions in your email tenant.
- Stuck? - If you are stuck on a step of the process, compare your screen to the screenshot shown for that step and ensure they look the same. Additionally, each section of the process includes a time stamp and link to a video going through the process step by step.
- Failed Submission – If you have submitted credentials and have subsequently been notified that your submission failed, we recommend redoing the setup process entirely. During this new setup, do not use anything created in the previous attempt, instead create a new service account with a new name, etc. If you use any previously created accounts, permissions, etc you will likely experience the same issue.
- Most offices that have resubmitted credentials after failing their first submission passed on their 2nd attempt.
- When redoing the process, it is critical that any field where you name something is filled in differently that your previous attempt. If you reuse names from a previous attempt this will likely cause an issue, even if you have deleted the previously created account / permission. We recommend putting a number at the end of the name that reflects the attempt # (i.e. MoxiEngage2 & Impersonation2).
- If you continue to have issues we recommend reaching out to your email provider and requesting assistance.
Related Resources
Microsoft Office Support
The following resources may provide additional information you need to perform the requisite tasks:
Compare Active Directory to Azure Active Directory