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.

Microsoft Graph for Events

Nylas now offers Microsoft Graph permissions for events only.

Prerequisites

Native Authentication

Microsoft has 2 types of Exchange authentication:

Administrators can choose which authentication flow to use.

Recommendation

We recommend using OAuth or Modern authentication for security reasons.

Basic Authentication

Exchange or Basic Authentication is a former authentication protocol for Microsoft. Basic authentication uses a username and password flow.

  1. Create a branded page where users will enter the login credentials.
  2. 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 off by adding exchange_server_host to the settings. See Exchange Auto-discovery for more.

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"
}'
  1. In the response, Nylas will return a one-time use code that you can exchange for an access_token.
  2. Now that you have your one-time use code, send a request to /connect/tokento get an access token.

Modern or OAuth Authentication

OAuth for Microsoft requires that you:

Microsoft Native Authentication
  1. Make sure you have followed the steps to Create an Azure App.
  2. Redirect the user to your OAuth login page.
  3. Microsoft sends the authentication code to your application.
  4. 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
  5. Microsoft returns the refresh_token.
  6. Then make a request to /connect/authorize using the microsoft_client_id, microsoft_client_secret (from your Azure app), and microsoft_refresh_token.

Microsoft Refresh Token Scopes

  • tenant to common
  • scope to offline_access https://outlook.office365.com/EAS.AccessAsUser.All https://outlook.office365.com/EWS.AccessAsUser.All openid profile User.Read

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"
}'
  1. Nylas returns a one-time use authorization code.
  2. Make a request to /connect/token

Example POST Exchange the Token Request

Microsoft will be deprecating Basic Authentication support for all Exchange Online accounts as of October 1, 2022.

Learn more through our Microsoft Exchange Online and Basic Auth Changes guide.

curl -X POST "https://api.nylas.com/connect/token" -d '{
  "client_id": "{client-id}",
  "client_secret": "{client-secret}",
  "code": "{nylas_code}"
}'
  1. Nylas returns an access_token for the account.
  2. Go through Domain Verification.
  3. Become a Microsoft Verified Publisher.

Hosted Authentication

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

Hosted Authentication for Microsoft requires that you:

Microsoft Hosted Authentication Steps

  1. Create an Azure App.
  2. Follow the Hosted Authentication steps.

Nylas will attempt to detect the exchange host. If we are unable to, then 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 off auto-discovery 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 are unable to find the server, they will need to enter the server information.

Deactivate Autodiscovery

Nylas will attempt to automatically discover the exchange host. You can turn this off by adding exchange_server_host to the settings.

Some providers don't allow you to turn off the discovery settings:

  • Office 365 Native Authentication

Microsoft Exchange ActiveSync

Nylas can sync nearly all Exchange accounts. The provider attribute should be set to exchange.

Theexchange_server_host value is optional. If omitted, Nylas Cloud will attempt AutoDiscoveryfor the server host or endpoint.

Keep in Mind

  • When requesting the refresh token from Microsoft make sure you set tenet and scope properly.
    • 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 preferred for security.
  • Using Native Authentication you can turn off exchange auto-discovery.

Scopes

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

Example Apps

We have created several Microsoft Authentication applications so you can see how to implement the process in your app.

What’s Next?