Only show these results:

Microsoft Authentication

When you authenticate accounts with Microsoft, you need to decide if you want to use OAuth or Basic Authentication. Administrators can configure their app to use either protocol.

Prerequisites

We recommend reading our guides on Hosted and Native Authentication:

Native Authentication

Microsoft has two types of Exchange authentication:

Administrators can choose which authentication protocol to use.

For security reasons, we recommend using OAuth or Modern Authentication. Additionally, Microsoft will be deprecating Basic Authentication support for all Exchange Online accounts as of October 1, 2022.

Basic Authentication

Exchange or Basic Authentication is a former authentication protocol for Microsoft. Basic Authentication uses a username and password flow. The steps to set up Basic Authentication are:

  • Create a branded page where users will enter their login credentials.
  • Make a request to /connect/authorize with the user-provided credentials in the settings and required scopes.

Autodiscovery

Nylas will attempt to automatically discover the exchange host. You can turn this feature off by adding exchange_server_host to the settings. See Exchange Auto-discovery for more information.

Exchange Accounts Example 

curl -X POST https://api.nylas.com/connect/authorize -d '{
    "client_id": "nylas_client_id",
    "name": "Nyla the Cheetah",
    "email_address": "[email protected]",
    "provider": "exchange",
    "settings": {
        "username": "[email protected]",
        "password": "MakeEmailSuckLess",
        "exchange_server_host": "exchange.nylas.com"
    },
    "scopes": "email.read_only,calendar.read_only,contacts.read_only"
}'
  • In the response, Nylas will return a one-time use code that you can exchange for an access_token.
  • Now that you have your one-time use code, send a request to /connect/token to get an access token.

Modern or OAuth Authentication

OAuth for Microsoft requires that you do the following:

Microsoft Native Authentication

To set up Modern or OAuth Authentication, follow the steps below:

  • Make sure you've created an Azure App.
  • Redirect the user to your OAuth login page.
  • Microsoft then sends the authentication code to your application.
  • Request the refresh_token from Microsoft. When requesting the refresh token, set tenant to common and set scope to offline_access https://outlook.office365.com/EAS.AccessAsUser.All https://outlook.office365.com/EWS.AccessAsUser.All openid profile User.Read
  • Microsoft then returns the refresh_token.
  • Make a request to /connect/authorize using the microsoft_client_id, microsoft_client_secret (from your Azure application), and the microsoft_refresh_token.

Example Microsoft POST Send Authorization Request 

curl -X POST https://api.nylas.com/connect/authorize -d '{ 
    "client_id": "nylas_client_id",
    "name": "Nyla the Cheetah",
    "email_address": "[email protected]",
    "provider": "office365",
    "settings":{
        "microsoft_client_id":     "{microsoft_client_id}",
        "microsoft_client_secret": "{microsoft_client_secret}",
        "microsoft_refresh_token": "{microsoft_refresh_token}",
        "redirect_uri":            "https://example.com/redirect", # Redirect URI that was originally used to get the refresh token        
    },
    "scopes": "email.read_only,calendar.read_only,contacts.read_only"
}'
  • Nylas returns a one-time use authorization code.
  • Make a request to /connect/token.

Example POST Exchange the Token Request 

curl -X POST "https://api.nylas.com/connect/token" -d '{
  "client_id": "{client-id}",
  "client_secret": "{client-secret}",
  "code": "{nylas_code}"
}'

Hosted Authentication

Hosted Authentication follows the OAuth 2.0 process. Nylas takes care of the authentication when using Hosted Authentication.

Hosted Authentication for Microsoft requires that you do the following:

Microsoft Hosted Authentication Steps

Nylas will attempt to detect the exchange host. If we're unable to, the user is given the option to enter the exchange host.

Exchange Host Enter Credentials

Exchange Autodiscovery

Native Authentication

When using Native Authentication, Nylas will attempt to automatically detect the provider. You can turn auto-discovery off for Exchange accounts by specifying the exchange_server_host in the settings.

Hosted Authentication

When using Hosted Authentication, Nylas attempts to discover the Exchange server and guide the user through authentication. If we're unable to find the server, the user will need to enter the server information.

Deactivate Auto-discovery

You can turn auto-discovery off by specifying the exchange_server_host in the settings.

Some providers, such as Office 365 Native Authentication, don't allow you to turn off the discovery settings.

Microsoft Exchange ActiveSync

Nylas can sync the majority of Exchange accounts. The provider attribute should be set to exchange.

The exchange_server_host value is optional. If it's not present, Nylas Cloud will attempt auto-discovery for the server host or endpoint.

Things to Keep in Mind

  • When requesting the refresh token from Microsoft make sure you properly set the tenant and scope:
    • Set tenant to common
    • Set scope to offline_access https://outlook.office365.com/EAS.AccessAsUser.All https://outlook.office365.com/EWS.AccessAsUser.All openid profile User.Read
  • OAuth is the preferred authentication method for security reasons.
  • You can turn off Exchange auto-discovery if you're using Native Authentication.

Scopes

Before authorizing a user, make sure you have the correct Nylas scopes in your request. If you need to change scopes, the user will have to re-authenticate.

Example Apps

We've created several Microsoft Authentication applications so you can see how to implement the process in your app:

What’s Next?