Version:
Only show these results:

Migrate Microsoft users from v2.x to v3

In Nylas v3, the Microsoft connector (provider: microsoft) allows end users to authenticate with several different Microsoft products so they can connect to your project.

✨ Want a version of this guide tailored to your project? Check out Nylas Migration Station!

To authenticate users who use Microsoft Exchange on-prem services for email and calendar, you must add a separate EWS connector. Nylas no longer supports Exchange on-premises service accounts.

Microsoft accounts which used Basic Auth to authenticate are no longer supported by Microsoft or Nylas. Microsoft required users of hosted Exchange servers, including Office 365/Microsoft 365 for business (not personal accounts) to upgrade to Modern Authentication in 2022, so these types should authenticate normally using the Microsoft connector.

For all other "Microsoft" account types, the Nylas v2 Import process reviews the account, and attempts to migrate it to v3. For more details on which accounts can be migrated, see Microsoft account import compatibility in v3.

⚠️ Nylas v3 requires that you upgrade your Exchange scopes to use Graph scopes instead. Because the upgrade to Nylas v3 includes this scope update, any Microsoft users not already using Graph must re-authenticate to accept the new v3 scopes.

Microsoft v2 to v3 import and configuration process

Before you start these steps, make sure you followed the steps in the Migrating app data instructions to link your organization, link the v2 application to the v3 application, and import the v2 app settings to the v3 app.

📝 If you upgrade a v2 Azure app instead of creating a new one, you still need to re-verify the app with Microsoft and re-authenticate your end users. Upgrading does not save you any time, so Nylas strongly recommends you create a new Azure app for clarity. However, if you must upgrade a v2 app, see Upgrade Azure app to use Microsoft Graph.

  1. Determine the Graph scopes your project needs by either translating your old v2 Exchange scopes, or by using the v3 scopes documentation.
  2. Create a new Azure app using the v3 instructions.
  3. Add the Graph scopes to your Azure auth app's Entra ID system (previously "Azure ID"). For more information, see Microsoft's official Configure Azure AD Graph permissions for an app registration guide.
  4. Add the v3 Authorized redirect URIs:
    • For U.S. Hosted authentication use https://api.us.nylas.com/v3/connect/callback.
    • For E.U. Hosted authentication use https://api.eu.nylas.com/v3/connect/callback.
  5. At this stage you might want to start the process of getting the app verified for production use.
  6. If you haven't already, run the Nylas Import tool. Nylas creates an unconfigured Microsoft connector, and a v3 Exhange on-prem connector if needed.
  7. Run the Nylas batch account migration tool. Nylas imports any v2 accounts that can be imported.
  8. Use the API to edit the Microsoft connector that the Import process created so that it uses the client ID and client secret of your Graph-compatible Azure auth app.
curl --location --request PATCH 'http://api.us.nylas.com/v3/connectors/microsoft' \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "settings": {
        "client_id": "<AZURE_CLIENT_ID>",
        "client_secret": "<AZURE_CLIENT_SECRET",
        "tenant": "<AZURE_TENANT>" // optional. can be tenant ID or common
    }
}'
  1. Prompt your end users to reauthenticate with Nylas, if necessary.

🔍 You can have only one connector for each provider per Nylas application. If you use more than one provider auth app for each provider (sometimes called "multi-tenant"), you must set up connector credentials for additional tenants.

Microsoft account import compatibility in v3

The Nylas v3 Microsoft connector allows your end users to authenticate with several different Microsoft products so they can connect to your project. This includes:

  • Microsoft cloud email accounts using OAuth
  • Microsoft 365 (previously called Office 365)
  • Exchange Online
  • Microsoft personal accounts
  • Live
  • Outlook
  • Hotmail

Accounts using Microsoft Exchange on-prem require a separate Exchange on-prem (EWS) connector.

When you run the Import tool, Nylas attempts to copy all Microsoft accounts to the linked v3 application. However, not all of them will be immediately compatible, and some will need to reauthenticate. You can think of migrating accounts falling into these categories:

  1. Accounts that are using token authentication and using Graph scopes already are automatically migrated to the v3 application. These accounts can continue using your project without reauthenticating, after you reconfigure your provider auth app.

  2. Accounts that are using token auth, but not using Graph scopes in v2 are migrated to the v3 application, but appear in an invalid state. After you reconfigure your provider auth app to use Graph scopes, these users can reauthenticate using OAuth so they can accept the new Graph scopes.

  3. Accounts that use a password to authenticate are migrated to the v3 application, and appear in an invalid state. After you reconfigure your provider auth app to use Graph scopes, these users can reauthenticate using their passwords to accept the new scopes. This also applies to Microsoft Exchange on-prem accounts, which must use a separate EWS connector.

  4. Personal accounts on Hotmail, Live, and Outlook cannot be imported, however after you reconfigure your provider auth app to use Graph scopes, the user can completely reauthenticate on the v3 application.