# Creating an Azure auth app

Source: https://developer.nylas.com/docs/provider-guides/microsoft/create-azure-app/

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

## Calculating scopes

If you're authenticating with Microsoft, you must use Microsoft Graph scopes (also sometimes called "feature permissions" or "API permissions").

If you're starting a new project, Nylas recommends you make a list of the APIs your project uses, then compile a list of the scopes you need using the [scopes documentation](/docs/dev-guide/scopes/). It's a security best practice to only request scopes that you actually use, however for development purposes, you might choose broader scopes than your production app needs.

You'll add these scopes to your Azure auth app's Entra ID system (previously "Azure ID") in the [Enable required APIs](#enable-required-apis) step below. For more information, see Microsoft's official [Configure Azure AD Graph permissions for an app registration guide](https://learn.microsoft.com/en-us/graph/migrate-azure-ad-graph-configure-permissions).

As you work with Nylas, you might need to update your scopes for specific APIs (for example, you might want Write permissions for your users' messages). You can find API-specific scope information throughout this documentation:

- [Email API scopes](/docs/dev-guide/scopes/#email-api-scopes)
- [Calendar API scopes](/docs/dev-guide/scopes/#calendar-and-events-api-scopes)
- [Scheduler API scopes](/docs/dev-guide/scopes/#scheduler-api-scopes)
- [Contacts API scopes](/docs/dev-guide/scopes/#contacts-api-scopes)
- [Notification scopes](/docs/dev-guide/scopes/)

## Create an Azure OAuth application

> **Success:** 
> **If you don't already have one, [**create your free Microsoft Azure account**](https://azure.microsoft.com/en-us/free/)**. You'll use this account to create the Microsoft developer application that you use to authenticate users using OAuth with Nylas.

First, you need to create an Azure OAuth app:

1. In the Microsoft Azure Portal, search for and click **App registrations**, then **New registration**.
2. Give your application a name. This name will be visible to your users.
3. Set the audience for the app to **Accounts in my organizational directory and personal Microsoft accounts**. This allows your user to log in using any Microsoft account.
   If you're building an internal application (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**.
4. Set the **Redirect URI platform** to **Web** and enter your project's redirect URI.
   - **Hosted Auth**: `https://api.us.nylas.com/v3/connect/callback` (U.S. region) or `https://api.eu.nylas.com/v3/connect/callback`. (E.U. region).
   - **Bring Your Own Authentication**: Your project's callback URI.
5. Review Microsoft's Platform Policies, then click **Register**.
   ![Microsoft Azure Portal displaying the "Register an application" page.](/_images/microsoft/azure/v3-register-azure-app.png "Register your application")

## Enable required APIs

> **Success:** 
> **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](#optional-enable-required-apis-with-manifest).

After you [create your OAuth app](#create-an-azure-oauth-application), you must add the required permissions to your Azure app. This enables the APIs that your application requires.

1. In the Microsoft Azure Portal, go to **Home > App registrations** and select your application.
2. From the left navigation menu, select **API permissions**.
3. Click **Add a permission**.
4. Select **Microsoft Graph** from the list of APIs.
5. Select **Delegated permissions**.
   - If you plan to use bulk authentication, select **Application permissions** and add all Microsoft Graph scopes that your project needs access to. For more information, see [Use a Microsoft bulk authentication grant](/docs/v3/auth/bulk-auth-grants/#use-a-microsoft-bulk-authentication-grant).
6. Enable the following permissions:
   - `offline_access`: Read and update user data, even when the user is offline.
   - `openid`: Sign users in to the app.
   - `profile`: View users' basic profiles.
   - `User.Read`: Allow users to sign in to the app, and allow the app to read their profiles.
   - [At least one feature permission](/docs/dev-guide/scopes/): These permissions, also known as "scopes", allow Nylas to read data from the provider.
7. Click **Add permissions**.

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](#optional-enable-required-apis-with-manifest) or [create a new Azure auth app](#create-an-azure-oauth-application).

For more information, see [Microsoft's official permissions reference](https://learn.microsoft.com/en-us/graph/permissions-reference).

### (Optional) Enable required APIs with manifest

If you use the application manifest, you can update an Azure app directly by editing its JSON. For more information, see [Microsoft's official AD Manifest documentation](https://learn.microsoft.com/en-us/entra/identity-platform/reference-app-manifest?WT.mc_id=Portal-Microsoft_AAD_RegisteredApps).

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

1. In the Microsoft Azure Portal, select **Manifest** from the left navigation menu.
1. Find `requiredResourceAccess` in the code panel.
1. Update `requiredResourceAccess` to include the following permissions:
   - `offline_access`
   - `openid`
   - `profile`
   - `User.Read`
   - [At least one feature permission](/docs/dev-guide/scopes/)
1. Click **Save**.

## Create OAuth credentials


Next, create your OAuth credentials:

1. In the Microsoft Azure Portal, search for and click **App registrations** and select your application.
2. Select **Certificates & secrets** from the left navigation.
3. Click **New client secret**, enter a short description, and set the expiration date to **730 days (24 months)**.
   <img
     src="/_images/microsoft/azure/azure_add_client_secret.png"
     alt="Microsoft Azure Portal displaying the Add a Client Secret dialog."
     style="height:200px;"
   />
4. Click **Add**.
5. Copy the value from the Azure Client Secrets page and save it to your secrets manager.
> **Warn:** 
> ⚠️ **Be sure to save the client secret value somewhere secure**. 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](/docs/dev-guide/best-practices/#store-secrets-securely).
   ![Microsoft Azure Portal displaying the "Client secrets" page.](/_images/microsoft/azure/azure_app_client_secrets.png "Azure client secrets")
6. Navigate to the **App registrations** page and copy the **Application (client) ID** for your app.

All Azure credentials include an expiration date. When they expire, you'll need to refresh or regenerate them.


## Add a Microsoft connector to Nylas

Finally, you need to add a Microsoft connector to your Nylas application. You can create a connector either [using the Nylas Dashboard](#create-connector-using-the-nylas-dashboard), or by [making an API request](#create-connector-using-the-nylas-api).

### Create connector using the Nylas Dashboard

1. Log in to the Nylas Dashboard, and navigate to the Nylas application you're creating the connector for.
1. Select **Connectors** from the left navigation.
1. In the **Microsoft** tile, click the add symbol (**+**).
1. Under **Microsoft credentials**, enter your **Azure client ID** and **Azure client secret**.
   - Set the **Azure tenant** to `common` to allow authentication for accounts that are outside of your organization.
1. Under **Authenticate scopes**, select the required scopes.
1. Click **Save**.

### Create connector using the Nylas API

To add a connector using the Nylas API, make a [Create Connector request](/docs/reference/api/connectors-integrations/create_connector/). The following code sample demonstrates how to use your Azure app's client ID and secret to add the Microsoft connector to Nylas.

```bash
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": "<AZURE_CLIENT_ID>",
      "client_secret": "<AZURE_CLIENT_SECRET>",
      "tenant": "common"
    },
    "scope": [
      "offline_access",
      "openid",
      "profile",
      "User.Read",
      "Calendars.Read",
      "Calendars.ReadWrite",
      "Mail.ReadWrite",
      "Mail.Send"
    ]
  }'
```

> **Success:** 
> **Tip**: Use `tenant: "common"` to allow authentication for accounts that are outside of your organization.

## Update your Azure client secret

Microsoft's Azure client secrets expire after two years. When a secret expires, it invalidates the associated Nylas grants. For best practices on updating your Azure client secret, see [How to renew Microsoft Azure client secret for your Nylas application](https://support.nylas.com/hc/en-us/articles/11833396105757-How-to-Renew-Microsoft-Azure-Client-Secret-for-Your-Nylas-Application).