How to Use the EWS API to Authenticate Accounts Into Your App

How to Use the EWS API to Authenticate Accounts Into Your App

Learn how to use the EWS API to authenticate accounts into your app and discover how Nylas makes it easy to integrate full email, calendar, and contacts functionality.

Ben Lloyd Pearson | May 7, 2020

Microsoft’s Exchange Web Services (EWS) API provides users with an intuitive interface that allows developers to add full Exchange data and functionality into their app. With direct SOAP implementation, clients can send and receive web service messages from client applications, portal applications, and service applications, an access nearly all the information stored in an Exchange Online, Exchange Online as part of Office 365, or an Exchange server mailbox by simply using the EWS Managed API. 

This article will cover the major components of the EWS API and explain just what it takes to build a full integration with EWS accounts. It will also demonstrate how the Nylas Communications Platform abstracts away much of the complexity of building a direct integration with the Microsoft EWS API, enabling you to build your email, calendar and contacts integration seamlessly and efficiently.

EWS Authentication Overview

There are two primary way to setup an EWS environment for development purposes:

Once that is established, you are ready to authenticate your development environment, utilizing standard web authentication protocols to help secure the communication between your application and the Exchange server. For those users that are targeting Exchange Online, the authentication method that you choose must use HTTPS to encrypt the requests and responses that your application sends. We recommend that you use HTTPS for any request that your application sends to an EWS endpoint to help secure communication between your application and an Exchange server. 

Exchange provides the following authentication options for you to choose from:

  • OAuth 2.0 (Exchange Online only)
  • NTLM (Exchange on-premises only)
  • Basic (Will be deprecated on October 13, 2020)

The authentication method that you choose depends on the security requirements of your organization, whether you are using Exchange Online or Exchange on-premises, and whether you have access to a third-party provider that can issue OAuth tokens. 

OAuth Authentication

OAuth is the gold standard for app to app authentication, and it should be used whenever possible. We recommend all applications use OAuth to connect to all Exchange Online services. The advantage in security over basic authentication is worth the additional work required to implement OAuth in your application. With that important point out of the way, there are also some disadvantages that you should be aware of.

Advantages
  • OAuth is an industry-standard authentication protocol.
  • Authentication is managed by the third-party provider. Your application doesn’t need to collect and store the Exchange credentials.
  • Your app only receives an opaque token from the authentication provider, so a security breach in your application can only expose the token, not the user’s Exchange credentials. This means better security for you with less worry about protecting sensitive data.
Disadvantages
  • OAuth relies on the EWS authentication service. This can impose additional costs on your organization or your customers.
  • The OAuth standard is more difficult to implement than basic authentication because you need to integrate your application with both the authentication provider and the Exchange server.

In order to minimize these disadvantages, we recommend using the Microsoft Azure Active Directory Authentication Library (ADAL) to authenticate users to Active Directory Domain Services (AD DS) in the cloud or on-premises and then obtain access tokens for securing calls to an Exchange server. Exchange Online requires tokens issued by the Azure Active Directory service, which is supported by the ADAL. But you can use any third-party library for this action.

Microsoft offers two types of OAuth permissions to access EWS APIs in Exchange Online, delegated permissions and application permissions. Before you proceed with the tutorial, you will need to choose the specific permission type you wish to use:

  • Delegated permissions are used by apps that have a signed-in user present. For these apps, either the user or an administrator consents to the permissions that the app requests and the app can act as the signed-in user when making API calls.
  • Application permissions are used by apps that run without a signed-in user present; for example, apps that run as background services or daemons and can access multiple mailboxes.

To use EWS OAuth, you first need to register your application, and get an application ID issued by Azure Active Directory. The EWS docs contain a bunch of code examples that demonstrate how to get access tokens for delegated and application permissions.

NTLM Authentication

NTLM authentication is only available for on-premises servers. For applications that run inside of a corporate firewall, integration between NTLM authentication and the .NET Framework provides a built-in means to authenticate your application:

Advantages
Disadvantages
  • Users must be logged on to a domain to use NTLM authentication.
  • It can be difficult to access email accounts that are not associated with the user’s domain account.
  • Service applications must have a domain account to take advantage of NTLM authentication.

Take a look at the NTLM Authentication code examples in the docs to learn more about how to use this feature. 

Basic Authentication

As its name suggests, basic authentication provides only a basic level of security for your client application; your app must store the username and password and use it to log into Exchange on behalf of your user. We recommend that all applications use OAuth or NTLM, and not basic authentication, particularly considering that this will be deprecated in October 2020.. Really, the only reason you should use this method is for testing basic interactions with the EWS API.

Nylas Makes Exchange Integrations Easy and Maintenance-Free

The Nylas Communications Platform integrates with 100% of email, calendar, and contacts providers, including Exchange, Office365, and Outlook. With Nylas, you can build a full email, calendar, and contacts integration in a fraction of the time it would take to build a direct integration with Exchange. Let’s take a look at the features Nylas offers to make it dead simple to build your first email, calendar, and contacts integration.

Nylas Hosted Auth

Nylas Hosted Auth is the quickest and easiest way to setup user authentication for your app. Simply redirect users to a Nylas login page and we’ll handle the rest including auto-detection of third party providers and managing token exchanges with providers like Microsoft.

Illustration of the Nylas Hosted Auth service that integrates with 100% of email, calendar, and contacts providers, including Google

The Nylas Hosted Auth process is very similar to authentication with the the EWS OAuth authentication, but with some added magic to make your life much easier.

  1. Your app redirects a user to Nylas Hosted Auth and provides a list of email, calendar, and contacts scopes you would like to access.
  2. Nylas auto-detects the email account provider, and initializes the appropriate authentication process with the third-party API. In the case of Exchange accounts, Nylas initializes the EWS OAuth consent process.
  3. After the user logs in to their account, Nylas redirects them back to your app, and returns the appropriate OAuth credentials. If you’re building a server-side app, Nylas returns an authorization code that can be exchanged for a user access token. If you’re app is client-side, Nylas returns the access token directly.
  4. Your app uses the access token to make requests to the Nylas Email, Calendar, and Contacts APIs on behalf of the users.

Then, you can make a request to the Account endpoint to return information about the connected user account.

$ curl -X GET  https://api.nylas.com/account -H 'Authorization: Basic SVNz****'
{
    "id": "awa6ltos***",
    "account_id": "awa6lto***",
    "object": "account",
    "name": "Your User",
    "email_address": "[email protected]",
    "provider": "eas",
    "organization_unit": "folder",
    "sync_state": "running",
    "linked_at": 1470231381,
}
There are two key components of Nylas Hosted Auth that makes development easier:
  • Nylas auto-detects 100% of email, calendar, and contacts providers, even for Exchange organizations that use their own company domain for their email accounts. Additionally, you can connect user accounts for any other third party email, calendar, and contacts provider with no additional development work.
  • Nylas handles negotiating with third party providers to manage OAuth credentials to ensure user accounts are always connected and synced. 
Not to mention, the Nylas offers a modern REST interface that returns standard JSON, which is much easier to work with than the dated SOAP/XML interface Exchange provides. Nylas also provides SDKs for Python, Java, Node.js, and Ruby, to make getting started dead simple, where EWS is limited to .NET environments.

Focus on The Features Your Users Love

Ultimately, Nylas allows you to more quickly build your email, calendar, and contacts integration so you can spend more time building the features your users love. There’s no need to become an expert at Exchange integrations when you build with Nylas.

The Nylas Email API

The Nylas Email API provides full access to your Exchange email inboxes to ingest email data, manage and download email attachments, create drafts and send emails, and search email inboxes for specific content.

Here’s an example that requests the latest email message from a user’s inbox:

$ curl -X GET 'https://api.nylas.com/messages?limit=1' -H 'Authorization: Bearer ACCESS_TOKEN'
[
    {
        "subject": "Got some torpedos you need to stop?",
        "body": "Have you heard about our new torpedo-jamming technology? ",
        "from": [
            {
                "email": "[email protected]",
                "name": "Hedy Lamarr"
            }
        ],
        "to": [
            {
                "email": "james****@yahoo.com",
                "name": ""
            }
        ],
        "date": 1557950729,
        "folder": {
            "display_name": "Inbox",
            "id": "7hcg****",
            "name": "inbox"
        },
        "unread": true,
        "starred": false,
        ...
    }
]

The Nylas Calendar API

The Nylas Calendar API enables full access to Exchange calendar and event data, and allows you to schedule events and send RSVP notifications.

Let’s take a look at a request to get a specific event off a user’s calendar

$ curl -X GET 'https://api.nylas.com/events/{id}' -H 'Authorization: Bearer ACCESS_TOKEN' 
{
    "title": "Meeting: Player Piano Radios",
    "description": "Let's chat about our new torpedo jamming technology.",
    "location": "Vienna",
    "owner": "Hedy Lamarr <[email protected]>",
    "participants": [
        {
            "email": "[email protected]",
            "name": "Hedy lamarr",
            "status": "yes"
        },
        {
            "email": "[email protected]",
            "name": "Your User",
            "status": "yes"
        },
    ],
    "when": {
        "object": "timespan",
        "end_time": 1408123800,
        "start_time": 1408120200
    },
    "read_only": false,
    "busy": true,
    "status": "confirmed",
    ...
}

The Nylas Contacts API

The Nylas Contacts API makes it easy to enrich your user’s experience with detailed information about the people in their Exchange Contacts Book.

Here’s an example of what a user’s contact looks like with the Nylas Contacts API:

$ curl -X GET 'https://api.nylas.com/contacts/{contact_id}' -H 'Authorization: Bearer ACCESS_TOKEN'
{
        "birthday": "1960-12-31",
        "company_name": "Player Piano Radios",
        "emails": [
            {
                "email": "[email protected]",
                "type": "work"
            }
        ],
        "given_name": "Hedy",
        "surname": "Lamarr",
        "job_title": "Radio Frequency Controller",
        "notes": "Has some interesting theories about torpedos involving player pianos",
        "office_location": "Vienna",
        "phone_numbers": [
            {
                "number": "1 110 919 1485",
                "type": "business"
            }
        ],
        ...
    }

Get Started With Nylas

Here are some resources to help you learn how to get started with Nylas.

About the Author

Ben is the Developer Advocate for Nylas. He is a triathlete, musician, avid gamer, and loves to seek out the best breakfast tacos in Austin, Texas.

Ready to Start Building?