Microsoft Exchange Online and Basic Authentication

As of October 1, 2022 Microsoft has deprecated Basic Authentication support for all Exchange Online accounts.

This deprecation affects:

Exchange Online Accounts (Microsoft 365/Office 365)
Exchange Server Accounts in a Hybrid Deployment

This deprecation doesn't affect:

Personal Accounts such as outlook.com, hotmail.com and MSN.

To learn more, you can read the announcement from Microsoft.

Important Dates to Keep In Mind

April 1, 2022: Nylas strongly encourages creating an Azure app for all customers that authenticate Exchange Online (Microsoft 365) accounts to prevent service disruption to your users. The reason for this recommendation is because of the following policy execution by Microsoft:

Starting April 1: Sometime in the second quarter of 2022, Microsoft will selectively pick tenants and disable Basic Auth for all affected accounts for a period of 12-48 hours. After this time, Basic Auth for these protocols will be re-enabled if the tenant admin has not already done so using Microsoft’s self-service tools.

September 30, 2022: Nylas has stopped supporting Basic Authentication for Exchange Online and Exchange Hybrid Deployment accounts for all Nylas applications. Users will need to re-authenticate using OAuth to start syncing data again.

October 1, 2022: Microsoft deprecated Basic Authentication for Exchange Online (Microsoft 365 accounts)

How to Prepare For These Changes

You must take the following steps ensure there are no disruptions to your integration:

Create an Azure App

Starting April 30, 2022, we will require an Azure application for all customers who want to sync Exchange Online accounts. You can follow the steps to create an Azure App.

In addition to adding the EWS / EAS scopes you use today, make sure that you have the required Graph permissions below for services you use:

Email Messages Read only > Mail.Read
Email Messages Read and Write > Mail.ReadWrite
Email Send > Mail.Send
Calendar Read and Write > Calendar.ReadWrite
Contacts Read Only > Contacts.Read
Contacts Read and Write > Contacts.ReadWrite

Since we will be moving the services over in phases, we ask that you keep your existing EWS/EAS scopes to avoid interruptions to your integration. After we complete the upgrade, we will provide an update when the EWS scopes can be removed.

Set Up OAuth Authentication

Once your Azure app is set up, any new Exchange Online & Microsoft 365 users will be automatically redirected to the OAuth process.

For existing users who have previously authenticated using Basic Auth, please follow the steps listed in the Re-Authenticating Existing Users section.

If you are using Native Authentication (called "Custom Authentication" in v3), you must build an app that uses OAuth for all re-authenticated accounts, as well as any new authentications. See the Nylas Microsoft Authentication guide for more information.

What is OAuth and why is it beneficial?

OAuth 2.0 is a modern, open standard for more secure authentication that doesn’t require sharing your credentials with third parties. It supports Single Sign On (SSO), Multi-Factor Authentication (MFA), granular scopes for access to end user data, and many other features to keep your data much more secure in comparison to password-based authentication, which provides none of these features.

Re-Authenticating Existing Users

You'll need to re-authenticate all existing users that are currently using Basic Authentication.

Identifying Affected Accounts

To identify affected accounts, use the [GET /a/{client_id}/accounts](/docs/api/v2/#get-/a/-client_id-/accounts) endpoint and filter by provider=eas or provider=ews, along with the authentication_method=password. This will return all accounts that are currently authenticated using Basic Authentication.

You'll need to re-authenticate all accounts that are returned. With the account email, you can start setting up Hosted Authentication by including the login_hint. If you'd prefer to use Native Authentication, you can set this up instead.

An example Python script on how to use this API to iterate through all accounts and detect the accounts that need to be migrated is below:

import requests
import json
import base64

nylas_client_id="<CLIENT_ID>"
nylas_client_secret="<CLIENT_SECRET>"
auth_header = base64.b64encode(nylas_client_secret.encode("utf-8") + b":")

headers = {
  b'Content-Type': b'application/json',
  b'Authorization': b'Basic ' + auth_header
}

pagination_offset = 0
pagination_limit = 50
exchange_providers = ["eas", "ews"]
exchange_password_accounts = []

while True:
    url = "https://api.nylas.com/a/{}/accounts?offset={}&limit={}".format(nylas_client_id, pagination_offset, pagination_limit)
    response = requests.request("GET", url, headers=headers)

    if response.status_code != 200:
        break

    data = response.json()

    for account in data:
        if account.get("provider") in exchange_providers and account.get("authentication_type") == "password":
            exchange_password_accounts.append(account)

    if len(data) < pagination_limit:
        break

    pagination_offset += len(data)

print(exchange_password_accounts)

Re-Authenticate Affected Users

Once you have identified the affected users, you'll need to re-authenticate them using the OAuth flow.

What's Next?

Create an Azure app