Version:
Only show these results:

Migrate Microsoft users from v2.x to v3

In Nylas v3, the Microsoft connector (provider: microsoft) allows 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 you can migrate, 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 users. Upgrading doesn't save you any time, so Nylas strongly recommends you create a new Azure app for clarity. 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 Exchange on-prem connector if needed.

  7. Run the Nylas batch account migration tool. Nylas imports any compatible v2 Microsoft accounts.

  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 'https://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
        }
    }'

  9. Prompt your users to re-authenticate 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.

Error when translating Graph IDs

When you migrate Microsoft Graph accounts from Nylas v2 to v3, Nylas makes a call to the Graph APIs to translate mutable object IDs to immutable IDs. However, sometimes this fails on the provider side because objects in your v2 Nylas database no longer exist on Microsoft. When this happens, Nylas returns the error type in the v3_provider_id field (for example, ”v3_provider_id”: “unable to translate to immutable Graph ID with providerError: ‘NotFound’”).

EWS mutable and immutable IDs

Nylas returns immutable IDs for Calendars and Folders when you migrate EWS accounts from v2 to v3. However, sometimes this fails on the provider side. When this happens, Nylas returns the object's mutable ID in Migration API responses.

📝 Mutable IDs in EWS are always longer than 90 characters. You can use this to differentiate mutable and immutable IDs in your project.

You can use the returned mutable ID in future requests to the Nylas Email, Calendar, and Contacts APIs, but Nylas will return the object's immutable ID in its response. You should store the immutable ID as a permanent object ID to use going forward.

Microsoft account import compatibility in v3

The Nylas v3 Microsoft connector lets your users 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 re-authenticate. 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 re-authenticating, 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 re-authenticate 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 re-authenticate 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. Nylas can't import personal accounts on Hotmail, Live, and Outlook. However, after you reconfigure your provider auth app to use Graph scopes, the user can completely re-authenticate on the v3 application.