Version:
Only show these results:
private-preview

Create a Microsoft Teams integration

This feature is a private preview release and should be used with caution. It may contain bugs, and its features and implementation will likely change before it is generally available.

Nylas offers the option to connect your end users' accounts to Microsoft Teams. This makes scheduling events using Teams much easier — they can simply configure their default settings in Teams, then create conferencing details by adding Teams to the event.

This page explains how to set up Microsoft Teams in your Nylas application.

Configure Azure application

To use Microsoft Teams with Nylas, you first need to create an Azure application. If you already have an Azure app, you can use it instead.

Upgrade to Microsoft Graph

Now that you have an Azure application, you need to upgrade it to Microsoft Graph. First, add the Graph scopes that you'll need for your integration:

  1. From the Azure Portal home page, search for App registrations and navigate to the resulting page.
  2. Select the application you want to configure.
  3. In the left navigation menu, click API permissions.
  4. Click Add a permission -> Microsoft Graph.
  5. Depending on the Nylas features you're using, add the following permissions:
    • Email messages — Read only: Mail.Read
    • Email messages — Read and Write: Mail.ReadWrite
    • Email messages — Send: Mail.ReadWrite and Mail.Send
    • Calendar — Read and Write: Calendar.ReadWrite
    • Contacts - Read only: Contacts.Read
    • Contacts — Read and Write: Contacts.ReadWrite
  6. Save your changes.

⚠️ Don't remove your existing Exchange Web Service (EWS) or Exchange ActiveSync (EAS) scopes. Nylas is migrating services to Microsoft Graph in phases. Your application might experience interruptions if you remove your existing EWS or EAS scopes. You'll receive an update from Nylas when you can safely remove them.

Microsoft Azure Portal displaying the "API permissions" page.

Re-authenticate end users

Next, you have to re-authenticate your end users so they can accept the new Graph scopes. You can either force them to re-authenticate, or send them a notification asking them to re-authenticate their account.

After your end users have granted Nylas the Microsoft Graph scopes, you can continue setting up your Teams integration.

Add OnlineMeetings permission

Your Azure application also needs the OnlineMeetings.ReadWrite permission. If you're adding this permission to an existing Azure app, your end users must re-authenticate for it to take effect.

  1. From the Azure Portal home page, search for App registrations and navigate to the resulting page.
  2. Select the application you want to configure.
  3. In the left navigation menu, select API permissions.
  4. Click Add a permission -> Microsoft Graph -> Delegated permissions.
  5. Search for OnlineMeetings.ReadWrite and add it to your Azure application.
  6. Save your changes.

Add redirect URIs

Now that you have your permissions set, you need to add your redirect URIs to the Azure application:

  1. From the Azure Portal home page, search for App registrations and navigate to the resulting page.
  2. Select the application you want to configure.
  3. In the left navigation menu, select Authentication.
  4. Click Add a platform -> Web.
  5. Add the redirect URI for your region:
    • U.S.: https://beta.us.nylas.com/connect/callback
    • E.U.: https://beta.eu.nylas.com/connect/callback
  6. Click Configure.
  7. Under Implicit grant and hybrid flows, enable Access tokens and ID tokens.
  8. Click Save.
  9. Under Supported account types, choose the type of application you're using:
    • Select Single tenant if you want to limit authentication to accounts from your specific organization. You'll need your tenant ID from the Overview page, and your Azure application must be MDM verified before you can publish it.
    • If you don't need to limit authentication, select Multitenant.
  10. Click Save.

Get your Azure client secret

💡 If you already have the client secret for your Azure application, you can skip this section. Go ahead and create your Teams integration!

Finally, you need to generate the client secret and value for your Azure application:

  1. From the Azure Portal home page, search for App registrations and navigate to the resulting page.
  2. Select the application you want to configure.
  3. In the left navigation menu, select Certificates & secrets.
  4. Click New client secret.
  5. Enter a description and set the duration that the secret should be valid.
  6. Save your changes.

The Azure portal displays your client secret and value.

⚠️ Be sure to save your client secret and value somewhere safe, like a secrets manager. For best practices, see Storing secrets securely.

Create a Microsoft Teams integration

Now that your Azure application is set up, you can create your Microsoft Teams integration!

📝 You'll need to repeat the following steps for each end user account that you want to connect.

Before you begin, use your terminal to convert your Nylas client ID and secret to Base64 format. Be sure to put a colon in between the two values, as in the example below.

echo '<NYLAS_CLIENT_ID>:<NYLAS_CLIENT_SECRET>' | base64

Next, you'll choose which type of integration you want to create: single tenant or multitenant. You'll use the same type that you set when you added your redirect URIs to your Azure app.

Create a single tenant Teams integration

A single tenant integration allows you to limit authentication to only accounts within your organization. You'll need your Azure application's tenant ID from the Azure Portal Overview page, and the app will need to be MDM verified before you can publish it.

When you have your tenant ID, make a POST connect/integrations request. Include your Base64 client ID and secret in the Authorization header, and your Azure application's tenant ID in the tenant field. If the request is successful, Nylas responds with an integration ID.

⚠️ You can pass multiple redirect URIs, but at least one must match the redirect URL for OAuth in your Azure application.

curl --location --request POST 'https://beta.us.nylas.com/connect/integrations' \
  --header 'Authorization: Basic <BASE64_NYLAS_CLIENT_ID_SECRET>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Teams Test app",
    "provider": "microsoft",
    "settings":
    {
      "client_id": "<AZURE_CLIENT_ID>",
      "client_secret": "<AZURE_CLIENT_SECRET>",
      "tenant": "<TENANT_ID>"
    },
    "redirect_uris": [
      "https://myapp.com/callback-handler"
    ],
    "expires_in": 1209600
  }'   
{
  "success": true,
  "data": {
    "id": "3d6d9d51-2269-434d-85b8-73d44bb86e24",
    "name": "Teams Test app",
    "provider": "microsoft",
    "redirect_uris": [
      "https://myapp.com/callback-handler"
    ],
    "expires_in": 1209600
  }
}

Create a multitenant Teams integration

Unlike a single tenant Teams integration, a multitenant integration allows any end user to authenticate, regardless of the organization they belong to.

To create a multitenant integration, make a POST connect/integrations request. Include your Base64 client ID and secret in the Authorization header, and set the tenant field to common. If the request is successful, Nylas responds with an integration ID.

⚠️ You can pass multiple redirect URIs, but at least one must match the redirect URL for OAuth in your Azure application.

curl --location --request POST 'https://beta.us.nylas.com/connect/integrations' \
  --header 'Authorization: Basic <BASE64_NYLAS_CLIENT_ID_SECRET>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Teams Test app",
    "provider": "microsoft",
    "settings":
    {
      "client_id": "<AZURE_CLIENT_ID>",
      "client_secret": "<AZURE_CLIENT_SECRET>",
      "tenant": "common"
    },
    "redirect_uris": [
      "https://myapp.com/callback-handler"
    ],
    "expires_in": 1209600
  }'   
{
  "success": true,
  "data": {
    "id": "3d6d9d51-2269-434d-85b8-73d44bb86e24",
    "name": "Teams Test app",
    "provider": "microsoft",
    "redirect_uris": [
      "https://myapp.com/callback-handler"
    ],
    "expires_in": 1209600
  }
}

Authenticate with Microsoft

Now that you have a Microsoft Teams integration, you'll need to authenticate an account with Microsoft. To do so, make a POST /connect/auth request. Include your Base64 client ID and secret in the Authorization header, and pass the ID of a connected account in account_id. If the request is successful, Nylas responds with an authentication URL.

curl --location --request POST 'https://api.us.nylas.com/connect/auth' \
  --header 'Authorization: Basic <BASE64_NYLAS_CLIENT_ID_SECRET>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "provider": "microsoft",
    "redirect_uri": "https://myapp.com/callback-handler",
    "expires_in": 43200,
    "account_id": "anz2nojgkfzfo4094wi291hzq",
    "scope":[
      "User.Read",
      "offline_access",
      "OnlineMeetings.ReadWrite",
      "openid",
      "profile",
      "EAS.AccessAsUser.All",
      "EWS.AccessAsUser.All"
    ]
}'   
{
  "success": true,
  "data": {
    "url": "https://beta.us.nylas.com/connect/login?id=nn9Gi0sZOdbULHuVTC8XOmLKZc1ftHlAeiAa",
    "id": "nn9Gi5sZOdbULHtVTC8DOmLKZc2ftHlAeiAa",
    "expires_at": 1632293094,
    "request": {
      "provider": "microsoft",
      "redirect_uri": "https://example.com/callback-handler",
      "scope": [
        "User.Read",
        "offline_access",
        "OnlineMeetings.ReadWrite",
        "openid",
        "profile",
        "EAS.AccessAsUser.All",
        "EWS.AccessAsUser.All"
      ],
      "account_id": "anz2nojgkfzfo4094wi291hzq"
    }
  }
}

Next, direct the end user to the authentication URL that Nylas returned. The end user must give consent to the scopes requested to authorize your Teams integration.

When the end user accepts the scopes, Nylas sends them to the redirect URI you specified during setup. Nylas also encodes the status of the grant, the grant_id, and the provider in the URI, as in the example below.

https://example.com/callback-handler?success=true&provider=microsoft&email=test5@testoffice365.com&grant_id=377a3784-bc39-4a5f-8f57-cecfa97ba74c#

🚀 Your authenticated end user can now use the Microsoft Teams integration! Remember, you'll need to set up a Teams integration for each end user you want to authenticate.

What's next?

FAQ

You've got questions? We have answers.

Can I autocreate a Teams event and add details manually?

No. You need to either use autocreate, or add the Teams event manually.

Can I customize the authentication process?

Your end users need to authenticate with Microsoft Teams to autocreate events. You can redirect them to a different page after the authentication flow is finished by setting the redirect URI.