Version:
Only show these results:

Set up Office 365 service accounts for Nylas v2

⛔️ As of May 2024, Microsoft deprecated the ApplicationImpersonation role in Exchange Online. For more information, see Microsoft's official blog post. Your existing accounts will remain connected to Nylas. To continue using Office 365 service accounts, upgrade to v3 and create a Service Account connector credential.

This page explains how to create Microsoft Office 365 service accounts for your v2 Nylas implementation.

Create Office 365 service accounts

⚠️ Depending on the configuration of an Exchange server's information cache, adding the "Service Account (Impersonation)" role to an account can take up to two hours to update. Keep this in mind as you verify your setup.

Follow these steps to create a service account for Office 365:

  1. Sign in to your Office 365 administrator account.
  2. From the list of apps, select Admin.
  3. Expand the Users section and select Active users.
  4. Click Add a user.
    A close-up of the Microsoft Office 365 Admin Center "Active users" page. The "Add a user" option is highlighted.
  5. Fill in the details for the new service account.
  6. Select Let me create the password and uncheck Require this user to change their password when they first sign in.
    A close-up of the Microsoft Office 365 Admin Center "Active users" page. The "Password settings" section is shown, and the "Let me create the password" option is selected.
  7. (Optional) Assign a license to the new account. The user doesn't need a license as long as the account they're linking through has a license.
    A close-up of the Microsoft Office 365 "Optional settings" page. The "Licenses" section is expanded, and the "Assign user a product license" option is selected.
  8. On the Optional settings screen, leave the settings as they are.

Set service account permissions

Next, set the permissions for the service account:

  1. Select Admin centers from the left navigation menu.
  2. Click Exchange. The Exchange Admin Center opens in a new window or tab.
  3. Click Permissions.
    A close-up of the Microsoft "Exchange admin center" page. The left navigation menu and the "Recipients" settings options are displayed.
  4. Click the plus symbol to add a new role group. A pop-up window is displayed.
  5. Click the plus symbol beside Roles to add a role to the role group.
  6. In the new window, select ApplicationImpersonation, then Add.
  7. Set up your new role group to match the following image.
    The Microsoft Exchange interface showing the "New role group" page. The fields are filled out with demo information, and the "ApplicationImpersonation" role is selected.
  8. Click the plus symbol to add a member.
  9. Search for the account you want to add permissions for, then click Add.
  10. Click OK.
    The Microsoft Exchange interface showing the "Service Account role group" page. The fields are filled out with demo information, and a role and a member are selected.

Authenticate Office 365 accounts

🔍 You must use a real account, not an alias, when authenticating end users with service accounts. The domain names for the service account and the end user's email address must match. For example, if the Service Account credential is service@example-1.com and the end user's email address is leyah@example-2.com, the auth process will fail.

To authenticate an end user with a service account's credentials using Modern Authentication/OAuth, pass the service account's refresh token in the settings object of your request. Be sure to indicate that the credentials belong to a service account by including service_account: true.

In the following example, the email_address field contains the end user's email address, and the settings object contains the service account's credentials.

curl -X POST https://api.nylas.com/connect/authorize -d '{ 
  "client_id": "<NYLAS_CLIENT_ID>",
  "name": "Leyah",
  "email_address": "leyah@example.com",
  "provider": "exchange",
  "settings":
  {
    "microsoft_client_id": "<AZURE_CLIENT_ID>",
    "microsoft_client_secret": "<AZURE_CLIENT_SECRET>",
    "microsoft_refresh_token": "<AZURE_REFRESH_TOKEN>",
    "redirect_uri": "<NYLAS_REDIRECT_URI>",
    "service_account": true,
    "eas_server_host": "server.host.com"     # Optional. If autodiscovery fails, specify the EAS host.
  },
  "scopes": "calendar"
}'

You can learn more about how to get a refresh token for your Microsoft application and when refresh tokens expire.

Keep in mind

As you use service accounts to authenticate Office 365 accounts, keep in mind that authenticating every account in your app might take a long time if the service account doesn't have an associated email inbox. You can monitor your application's logs through HttpProxy/Ews.

⚠️ Office 365 accounts with a business standard license and Azure Information Protection currently aren't compatible with Nylas.