With the evolution of authentication and API standards, integrating Exchange Online with ColdFusion requires adapting to new technologies. Previously, developers connected to Exchange Online using the cfexchangeconnection tag alongside various cfexchange tags like:

• cfexchangecalendar
• cfexchangecontact
• cfexchangemail
• cfexchangetask
• cfexchangefolder
• cfexchangeconversation
• cfexchangefilter

This approach involved manually specifying the Exchange Online EWS endpoint, and while it worked, recent changes introduced new challenges.

Challenges with the Existing Method

1. Basic Authentication Removal by Microsoft

Microsoft deprecated and permanently disabled Basic Authentication for Exchange Online in December 2022. Basic Authentication requires applications to send a username and password with every request, often storing these credentials on the device. While simple to implement, it poses serious security risks, such as credential theft and unauthorized access, especially if TLS is not enforced.

Since Basic Authentication was the default method for many Exchange services, its removal broke existing integrations, including those in ColdFusion. Although ColdFusion supported OAuth 2.0 through cfoauth, there was no mechanism to pass an access token to cfexchange tag’s. As a temporary solution, an update was released that allowed the OAuth token to be passed as a password, enabling authentication with Exchange Online services.

2. Retirement of EWS APIs for Exchange Online

Even after addressing the authentication issue, ColdFusion’s Exchange integration continued relying on Exchange Web Services (EWS)—a SOAP-based API primarily designed for on-premises Exchange servers. However, Microsoft has announced that EWS for Exchange Online will be officially retired on October 1, 2026.

The shift away from EWS is driven by its limitations compared to modern APIs. Being a legacy SOAP API, EWS lacks the efficiency, security, and flexibility of REST-based alternatives like Microsoft Graph API. Microsoft Graph provides improved performance, fine-grained access control, and better support for OAuth-based authentication, making it the recommended solution moving forward.

Recognizing these challenges, we took a proactive approach to transition ColdFusion’s Exchange integration to Microsoft Graph API before EWS is deprecated. By adopting Microsoft Graph API, we aim to minimize breaking code changes and provide a seamless experience for customers using Exchange Online services.

What are we Changing?

There is no change in behavior or functionality for existing on-premises Exchange services. So, if you’re using Exchange Server 2019—or any other on-prem Exchange server—good news! Nothing changes for you. However, for services using Exchange Online, a new attribute called “access_token” has been introduced in cfexchangeconnection tag. This attribute accepts an access token with Microsoft Graph API scopes, replacing the previous EWS API scopes. This shift provides better access control.

To obtain the access token, use the getOauthAccessToken function or the cfoauth tag, both of which integrate with Microsoft Identity Platform for seamless token retrieval. Since authentication now relies on access tokens instead of username and password, those attributes are no longer required. Additionally, Exchange Online is currently the only Exchange server that supports the access_token attribute which means server attribute is also optional for Exchange Online.

Code Samples

Below are two examples that retrieve ten mail messages from Exchange Online using both the newer and older approaches. These examples demonstrate that the only code changes required are related to connection establishment, as explained earlier.

Code Example (Newer Approach)
In this approach, we retrieve the access token using the GetOauthAccessToken BIF and establish the Exchange connection. This connection is then used to fetch mail messages via the cfexchangemail tag.

<cfscript>
  credentials = {type = "Microsoft",
                     providerConfig = {tenant = "your-tenant-id"},
                     clientid = "your-client-id",
                     scope = "offline_access mail.read",
                     secretKey = "your-secret-key",
                     granttype = "authorization_code"}
  response = GetOauthAccessToken(credentials);
</cfscript>

<cfexchangeConnection action = "open" access_token = "#response.access_token#"
                      connection = "newconnection"/>

<cfexchangemail action = "get" name = "tenMailMessages" connection = "newconnection">
  <cfexchangefilter name = "maxRows" value = 10>
</cfexchangemail>

<cfdump var = "#tenMailMessages#">

Code Example (Older Approach)
In contrast, this method directly passes credentials, requiring additional configurations such as the server endpoint, protocol, and application name. In the newer approach, these parameters are managed automatically through OAuth 2.0.

<cfexchangeconnection action = "open" connection = "old-connection"
                      username = "your-email@example.com" password = "your-password"
                      server = "https://outlook.office365.com/EWS/Exchange.asmx" protocol = "https"
                      exchangeApplicationName = "MyExchangeApp">

<cfexchangemail action = "get" name = "tenMailMessages" connection = "old-connection">
    <cfexchangefilter name = "maxRows" value = 10>
</cfexchangemail>

<cfdump var = "#tenMailMessages#">