Create an Azure auth app for Nylas v2

💡 If you're using Nylas v3, you should set up an Azure application for v3 instead. This page covers instructions specific to Azure apps for Nylas v2.

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

Before you begin

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 is used for authenticating end users using OAuth with Nylas.

Create an Azure OAuth application

⛔️ Do not authenticate end users to your production application before you've tested OAuth on your staging application. You cannot delete OAuth settings once you add them to Nylas.

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

Log in to the Microsoft Azure Portal.
Search for App registration and navigate to the resulting page.
Click New registration and give your application a name. This name will be visible to your end users.
Set the audience for the app to Accounts in any organizational directory. 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.
Set the Redirect URI platform to Web and enter your redirect URI.
- If you're using Hosted auth, enter https://api.nylas.com/oauth/callback (U.S. region) or https://ireland.api.nylas.com/oauth/callback (E.U. region).
- If you're using Native auth, enter your Nylas application's callback URI.
Review Microsoft's platform policies, then click Register.

The Microsoft Azure Portal displaying the "Register an application" page. The "Accounts in any organizational directory and personal Microsoft accounts" is selected.

Enable required APIs

After you create your OAuth app, you must add the required permissions to your Azure app:

In the Microsoft Azure Portal, search for App registration and navigate to the resulting page.
Select the Azure app that you want to configure.
In the left navigation menu, select Manifest.
- The application manifest lets you update an Azure app directly by editing its JSON. For more information, see Microsoft's official AD Manifest documentation.
Find the requiredResourceAccess in the code panel.
Update requiredResourceAccess to include the following manifest permissions. If you find existing manifest data, you must add these permissions to the existing data. If you need help, contact Nylas Support.
- Microsoft Graph:
  - offline_access: Allows the Azure app to maintain access to the data you've given it access to.
  - openid: Sign end users in with their Microsoft account.
  - profile: View end users' basic profiles.
  - User.Read: Sign in and read user profiles.
  - EAS.AccessAsUser.All: Access mailboxes via Exchange ActiveSync (EAS).
  - EWS.AccessAsUser.All: Access mailboxes as the signed-in user via Exchange Web Services (EWS).
Save your changes.

You've added all the required permissions to your Azure app. If you want to check the API permissions in the future, select API permissions from the left navigation menu.

The Microsoft Azure Active Directory Admin Center showing the "API permissions" page for an enterprise application. The "Place.Read.All" permission is highlighted, and its status shows the permission is not granted for the application.

Sample Azure Manifest

The following JSON includes the Graph permissions that Nylas requires when creating an Azure application.

...
"requiredResourceAccess": [
  {
    "resourceAppId": "00000003-0000-0000-c000-000000000000",
    "resourceAccess": [
      {
        "id": "cb8f45a0-5c2e-4ea1-b803-84b870a7d7ec",
        "type": "Scope"
      },
      {
        "id": "7427e0e9-2fba-42fe-b0c0-848c9e6a8182",
        "type": "Scope"
      },
      {
        "id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d",
        "type": "Scope"
      },
      {
        "id": "37f7f235-527c-4136-accd-4a02d197296e",
        "type": "Scope"
      },
      {
        "id": "14dad69e-099b-42c9-810b-d002981feec1",
        "type": "Scope"
      }
    ]
  },
  {
    "resourceAppId": "00000002-0000-0000-c000-000000000000",
    "resourceAccess": [{
      "id": "311a71cc-e848-46a1-bdf8-97ff7156d8e6",
      "type": "Scope"
    }]
  },
  {
    "resourceAppId": "00000002-0000-0ff1-ce00-000000000000",
    "resourceAccess": [
      {
        "id": "266d2589-20b5-4f91-9a03-89247d1be8da",
        "type": "Scope"
      },
      {
        "id": "3b5f3d61-589b-4a3c-a359-5dd4b5ee5bd5",
        "type": "Scope"
      }
    ]
  }
],
...

Create OAuth credentials

Next, you need to create your OAuth credentials:

From the Azure Portal, search for App registrations and navigate to the resulting page.
Select the Azure application that you want to configure.
In the left navigation menu, select Certificates & secrets.
Click New client secret.
Enter a description of the client secret, and set an expiration date of 24 months.
Click Add.
Copy the value from the Azure Client secrets page and save it to your secrets manager. Azure shows this value only once, and if you navigate away from this page you cannot retrieve the key value. For best practices, see Storing secrets securely.
Navigate to the App registrations page and copy the Application (client) ID for your app.

Add client ID and secret to Nylas

Finally, you need to add your Azure app's credentials to your Nylas application:

Log in to the v2 Nylas Dashboard.
Navigate to App settings > Authentication.
Add your Azure app's client ID and secret to Office 365 auth.
Click Save changes.

Get ready for production

You're all set up! 🎉 Now, it's time to get your Azure app ready for production.

Microsoft requires applications that access end user data go through a domain verification process. If you need help with the process, contact Nylas Support.

What's next?

Read the Nylas How to Create an Azure App blog post.

Video walkthrough

Prefer video? You can watch the Coding with Nylas live stream.