Only show these results:

Create an Azure auth app for Nylas v3

This page explains how to create and configure a Microsoft Azure OAuth application to use with Nylas v3.

Changes to Microsoft auth apps in v3

⚠️ If you're upgrading from Nylas v2 to v3, you must create a new Azure auth app. Your v2 Azure app is not compatible with v3, and v3 apps aren't compatible with Nylas v2. When you migrate your end users to the new auth app, they must re-authenticate their accounts and approve the app. Some end users might also need to get admin approval for it to access their accounts.

The steps to create and configure a Microsoft OAuth app for Nylas v3 should be pretty familiar, but some things have changed:

  • Supported account types have been updated to be Account in any organizational directory and personal Microsoft accounts. This allows for OAuth of personal accounts.
  • EWS- and EAS-related scopes have been removed.
  • Added a cURL request example to connect your Azure app to Nylas.
  • The Authorized redirect URIs have been updated:
    • 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.

Create an Azure OAuth application

💡 If you don't already have one, create your free Microsoft Azure account. You'll use this account to create the Microsoft developer application that you use to authenticate end users using OAuth with Nylas.

Follow these steps to create an Azure app for authenticating your users to Microsoft 365:

  1. Log in to the Microsoft Azure Portal.
  2. Search for App registration and navigate to the resulting page.
  3. Give your application a name. This name will be visible to your end users.
  4. Set the audience for the app to Accounts in any organizational directory and personal Microsoft accounts. This allows end users to log in using any Microsoft account.
    • If you're building an internal app (used only by members of your organization), you can restrict access to internal accounts only by setting the audience to Accounts in this organizational directory only.
  5. Set the Redirect URI platform to Web and enter your redirect URI.
    • If you're using Hosted auth, enter https://api.us.nylas.com/v3/connect/callback.
    • If you're using Custom auth, enter your app's callback URI.
  6. Click Register.
    Microsoft Azure Portal displaying the "Register an Application" page.

Enable required APIs

You can now enable the APIs that Nylas requires without modifying the manifest in your Azure app. If you prefer to use the manifest, you can follow the instructions in Enable required APIs with manifest.

After you create your OAuth app, you must add the required permissions to your Azure app. This enables the APIs that your application requires.

  1. In the Microsoft Azure Portal, select API permissions from the left navigation menu.
  2. Click Add a permission.
  3. Select Microsoft Graph from the list of APIs.
  4. Expand the OpenID permissions section and enable the following permissions:
    • offline_access
    • openid
    • profile
    • User.Read

If your Azure app was previously registered with a manifest, you might get the following error message:

One or more of the following permission(s) are currently not supported: EWS.AccessAsUser.All. Please remove these permission(s) and retry your request.

If this happens, you can either enable the required APIs with a manifest or create a new Azure auth app.

The table below describes the permissions that are available for Azure auth apps.

Azure Permission Required? Description
offline_access ☑️ Read and update end user data, even when the user is offline.
openid ☑️ Sign end users in to the app.
profile ☑️ View end users' basic profiles.
User.Read ☑️ Allow end users to sign in to the app, and allow the app to read their profiles.
Calendars.Read Read end users' calendars.
Calendars.ReadWrite Allow read and write access to end users' calendars.
Mail.Send Send email messages as an end user.
Mail.ReadWrite Allow read and write access to end users' email accounts.

For more information, see Microsoft's official permissions reference.

Enable required APIs with manifest

To enable the required APIs using an Azure manifest, follow these steps:

  1. In the Microsoft Azure Portal, select Manifest from the left navigation menu.
  2. Modify the manifest JSON to include the following permissions:
    • offline_access
    • openid
    • profile
    • User.Read
  3. Save your changes.

Create OAuth credentials

Next, you need to create your OAuth credentials:

  1. From the Azure Portal home page, go to Home > App registrations and select the application you want to configure.

  2. From the left navigation menu, select Certificates & secrets > New client secret.

  3. Enter a description of the client secret, and set an expiration date of 24 months.
    Microsoft Azure Portal displaying the Add a Client Secret dialog.

  4. Click Add.

  5. Copy the value from the Azure Client secrets page and save it to your secrets manager. Azure shows the value only once, and if you navigate away from this page you cannot retrieve the key value. For best practices, see Storing secrets securely.
    Microsoft Azure Portal displaying the "Client secrets" page.

  6. Navigate to the App registrations page and copy the Application (client) ID for your app.
    The Microsoft Azure Portal showing the "App registrations" page. One application is listed, along with its client ID.

Azure credentials include an expiration date. When these credentials expire you must refresh or regenerate them.

Add Microsoft connector to Nylas

Finally, you need to add the Microsoft connector to your Nylas environment. The following code sample demonstrates how to use your Azure app's client ID and secret to add the Microsoft connector to Nylas.

💡 Tip: Use tenant: "common" to allow authentication for accounts that are outside of your organization.

curl -X POST https://api.us.nylas.com/v3/connectors \
--header 'Authorization: Bearer <NYLAS_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
"name": "microsoft example",
"provider": "microsoft",
"settings":
{
"client_id": "<MICROSOFT_CLIENT_ID>",
"client_secret": "<MICROSOFT_CLIENT_SECRET>",
"tenant": "common"
},
"scope": [
"offline_access",
"openid",
"profile",
"User.Read",
"Calendars.Read",
"Calendars.ReadWrite",
"Mail.ReadWrite",
"Mail.Send"
]
}'