!!! This Microsoft Exchange Integration feature needs to be separately licensed. Once the information within this document has been verified on your end, please confirm and request the "MS Exchange" option to be enabled on your license from support@farmerswife.com. !!!
Use it to update user's events from farmerswife with MS Exchange 2010 or Exchange365 / Office365 user account's calendar.
By using this feature, farmerswife will update the schedule changes to the user's own Exchange Calendar.
The updated Events are read-only in the user's Calendar.
Users as well as Resources can be configured to use this feature – Resources do not need to have a web license enabled, but need a Web Permission Profile assigned which has "Exchange" enabled.
IMPORTANT update since 20. December 2022:
The farmerswife Exchange Integration had only supported "basic" authentication.
Microsoft is in process of stopping support for this on Exchange365 by "early January 2023"!
More info on this topic here: "Deprecation of Basic authentication in Exchange Online":
New "Use MS Azure AD Auth" support has been implemented!
This is available in farmerswife v7.0 Beta 4 since 14. December 2022 and v6.8 SP2after nightly rev. 20622 since 20. December 2022; and this is also part of the latest v6.8 Service Pack 3, which has been available since 16. January 2023.
Once this is configured, the Exchange Integration in farmerswife will be using a token from the then existing "Microsoft Entra ID (Azure Active Directory) Connector" settings.
(NOTE: Since 23/10/2023 “Microsoft Entra ID” - New name for “Azure Active Directory”; more info here:
https://learn.microsoft.com/en-gb/entra/fundamentals/new-name)
The "App Registration" on the MS Azure Portal is required, including adding/setting the correct "API Permissions"!
Required settings from Azure AD are: App Client ID, App Secret Key, Oauth 2.0 (v1) Token Endpoint, more info below.
Prerequisites:
This Microsoft Exchange Integration feature needs to be separately licensed.
In order to be eligible for the free-of-charge "Exchange" addition to your license, you first need to confirm that your on-premise MS Exchange or your "Office365" system is properly configured within its “Organizational Unit”.
The Exchange requirement: "ApplicationImpersonation" must be enabled on Azure!
MS Exchange365 and Azure AD IT knowledge on your side are pre-requisite.
Entra ID (Azure Active Directory) Connector "farmerswife" app
See these solution articles, on how to set up a "farmerswife API app" on Azure AD:
Microsoft Azure Active Directory Connector v1 & v2 - short version
Microsoft Azure Active Directory Connector v1 & v2 - detailed version
The above two Azure AD Connector solution articles are focused on setting up the "farmerswife" Azure Api App to use Azure AD for the user authentication etc. and this requires a different configuration.
The following 7 specific Azure API Permissions for the Exchange Integration are specific to only this integration:
These 7 specific Azure API Permissions are:
Microsoft Graph
> User.Read.All - Type: Application
Office 365 Exchange Online
> Calendars.ReadWrite.All - Type: Application
> EWS.AccessAsUser.All - Type: Delegated
> full_access_as_app - Type: Application
> Mail.Send - Type: Application
> Organization.ReadWrite.All - Type: Application
> User.Read.All - Type: Application
This Permission configuration is currently the only known working configuration.
To find the Office 365 Exchange Online Api permissions on the MS Entra admin center, go to "App registrations > Api permissions > click on the "+ Add a permission" option and then on the Request API permissions pop-up pane, click the APIs my organization uses tab and search for Office 365 Exchange Online and add it to your App. Now you can start adding the above mentioned API Permissions.
MS Exchange global user to authenticate
To write to the user's calendars "impersonation" via the EWS API is used.
Legacy/OLD: This is designed to work with MS Exchange 2010 (version 2007 might also work but it's not actively supported! e.g. a known limitation is no support for "viking characters" like å, ä etc.; also getting "impersonation" is harder to implement in MS Exchange 2007).
Configuring Exchange365 / Office365 Impersonation for the "Exchange Admin User":
based on: https://support.cloudm.io/hc/en-us/articles/360008478499-Setting-up-Application-Impersonation-for-Exchange-or-Office-365
LEGACY OLD Configuring Exchange Impersonation for the "Exchange Admin User":
(based on: http://msdn.microsoft.com/en-us/library/bb204095%28v=exchg.140%29.aspx)
Implement => "To configure Exchange Impersonation for specific users or groups of users" point 3.:
- New-ManagementRoleAssignment -Name:impersonationAssignmentName
- Role:ApplicationImpersonation -User:serviceAccount farmerswife
The Exchange requirement: "ApplicationImpersonation" must be enabled on Azure!
This requires "Organization Customization" to be enabled on Exchange.
In case of getting an error from Microsoft Exchange Online due to "Enable Organization Customization" is off, you can install PowerShell with the ExchangeOnline module enabled and run:
Enable-OrganizationCustomization.
=> pending to add more info from Microsoft here.
fw Server app side configurations:
In fw Server app > Setup > Users tab > you see here the Microsoft Exchange® Settings (must be licensed, see info above) AND Microsoft Azure Active Directory Connector which need to be configured:
This is an example of a working demo configuration (see below the example info format further down):
Note on above screen shot, that the Azure Active Directory Connector is configured but NOT enabled.
During the setup of the Exchange integration, the Azure Active Directory Connector must get enabled in order to configure and test it. Once it's working, and it's not used for user authentication, then disable the Azure Active Directory Connector as a best practice recommendation. See below more info, when using the "Test" button from the "Azure Active Directory Connector" section.
Even with the MS Azure Connector being disabled, when you use the "Test" button from the Exchange Settings section, this is the desired result for a correctly configured Exchange/Azure integration: "OK: Exchange Server Responded As Expected"
The Microsoft Exchange Settings fields are:
- Enabled: "No" (by default), change to "Yes" in order to use it.
- Web Services Port: 443
- Web Services URL:
- Exchange hosted on premise: https://IP-Of-Machine-Hosting-Exchange/EWS/exchange.asmx
- Office 365:"https://outlook.office365.com/EWS/Exchange.asmx"
NOTE: if using "Office 365" you also need to set:
"Time Zone (Only For Exchange 365):" set here the fw Server apps host machine local timezone.
- Exchange Admin User To Authenticate With: First try, by keeping this empty!
Legacy/OLD: Administrator@yourdomain.local = the "admin user" with enabled "Impersonation" - Password: First try, by keeping this empty. The password of "admin user" with enabled "Impersonation"
- "Test" button: Use this button to test the configuration and connection after Azure AD has been configured. If you get this response on the pop-up window: "OK: Exchange Server Responded As Expected", then Exchange and Azure are correctly configured.
- "Debug" button: This will create "EXCHANGE_DEBUG_..." files within the fw Server app's "system" folder. Only enable this during the initial configuration, while testing or while troubleshooting. If the integration is working fine, then disable it.
- Exchange User Primary Email For Impersonation Test: This "user" requires to have a "Mailbox" assigned. A minor "E1" license is sufficient.
- Event Status:
- Time Zone (Only For Exchange 365): Set here the fw Server apps host machine local timezone.
- Use MS Azure AD Auth: This is the new setting as per the above info, for this integration to no longer use "basic auth", but instead use the modern "Azure AD Auth".
The Microsoft Azure Active Directory Connector fields are:
- Enabled: No (by default), change to Yes to configure. Then change to No, if only Exchange365 is to be used.
- App Client Id: Use the above links to the Azure AD documentation on how to create these on your side.
- App Secret Key: Use the above links to the Azure AD documentation on how to create these on your side.
- Oauth 2.0 (v1) Token Endpoint: Use the above links to the Azure AD documentation on how to create these on your side.
- MS GRAPH API Endpoint: https://graph.microsoft.com
- User Groups: This does not have to be configured, if Azure AD is only to be used for the Exchanged integration!
- "Test" button: If there is no User Group configured, then you will get this error on using the "Test" button:
=> Simply ignore this "Bad Groups Request"; this is good news, since this means that the other Azure AD configuration is correct and working! This default Azure AD "Groups" test does not know, that Azure AD is only being used to authenticate for the Exchange integration.
Now start testing the integration by following the next steps!
Example of a working configuration of all involved settings:
Use this info to map the format against the available info on Entra ID; if the format matches with the below examples, then you have the correct info.
The Microsoft Exchange Settings fields are:
- Enabled: Yes
- Web Services Port: 443
- Web Services URL: https://outlook.office365.com/EWS/Exchange.asmx
- Exchange Admin User To Authenticate With: <empty>
- Password: <empty>
- "Debug" button: Yes
- Exchange User Primary Email For Impersonation Test: fw_support@somecompany.ex
- Event Status: Busy
- Time Zone (Only For Exchange 365): (UTC+01:00) Brussles, Copenhagen, Madrid, Paris
- Use MS Azure AD / Entra ID Auth: Yes
The Microsoft Azure Active Directory Connector fields are:
- Enabled: No
- App Client Id: 12345678~1234~1234~1234~123456789012
- App Secret Key: 12345~1234567890123456789012345678901234
- Oauth 2.0 (v1) Token Endpoint:
https://login.microsoftonline.com/abc45678~abc4~abc4~abc4~abc456789012/oauth2/token - MS GRAPH API Endpoint: https://graph.microsoft.com
The fw Client app side configurations:
In the Web Permissions: To grant access Users/Resources need to have a Web Profile assigned that has "Microsoft Exchange Calendar Sync" and optionally the "Schedule Change Email Sendout" enabled.
fw Client app Toolbox Settings:
In fw Client app > Toolbox > Settings > Web Share Settings > External Calendars / Schedule Changes Email Sendout / XML Export ... the "External Calendars" refers to the Exchange Integration:
- Update Time: Set here the time interval for each update. In production, Every 30 min. is recommended.
- Update Now button, use this button after setting the previously mentioned settings, to trigger the first update.
- Days Before: 0 or 7 . To choose how many days should be synced into Exchange
- Days After: 7, 14, 30, 60, 90, 180
Note: On the MS Exchange > Calendar older Events will not be updated, but remain in the state of the last sync.
We recommend to first try it out with a small group of users, before rolling it out to all users.
Some more related links which might be useful:
How to Discover Basic Auth Connections – Office 365 Basic Authentication Report
https://o365reports.com/2019/09/25/basic-authentication-exchange-online/#Basic_Authentication_Report
Exchange Online Admin portal: https://admin.exchange.microsoft.com
Azure Portal: https://portal.azure.com/
Office Online Admin: https://admin.microsoft.com/adminportal
Microsoft 365 Online login: https://login.microsoftonline.com/