Authenticate Exchange on-prem servers with Nylas
You can use the Nylas v3 EWS connector to connect to email accounts hosted on Exchange on-prem servers so you can use the Nylas Email, Calendar, and Contacts APIs with them.
⚠️ Microsoft announced the retirement of Exchange Web Services in 2022 and strongly recommended that all users migrate to use Microsoft Graph. Users on Exchange Online have already been migrated.
How is EWS different from the Microsoft connector?
Microsoft Exchange on-prem is a self-hosted application that an administrator can run on their own servers to provide email, calendar, and contacts directory features to their organization. This model predates modern cloud architecture, and requires anyone who wants to connect to this service (including Nylas) to make network requests directly to the specified server using the server address and port. While Microsoft has built some features such as autodiscovery to smooth this process, they are sometimes misconfigured, or not configured.
Microsoft announced the EWS retirement and is deprecating some of the services that supported it. However, Exchange is still installed on many private servers and used by many people.
Nylas v3 uses a separate connector to handle Exchange on-prem authentication requests because although it is technically a Microsoft product, it uses a totally different connection process.
If your project only uses the Email APIs, you can use an IMAP connector for these accounts instead.
Exchange on-prem minimum version
To use the Exchange on-prem connector with Nylas, the Exchange server must be running Exchange 2007 or later.
If you want to use starred messages, the server must be running Exchange 2010 or later.
Add an EWS connector
You can add an EWS connector to your application by making a POST /v3/connectors request, specifying the provider as ews, and including scopes that indicate which API services you want to use.
To add the EWS connector from the Dashboard:
- In the v3 Dashboard, navigate to the application you want to use EWS with.
- Click Connectors in the left navigation.
- Find the EWS item, and click the plus icon (+).
- Click the EWS connector and select the scopes you want to use.
You must set Nylas-defined scopes on the EWS connector to indicate which API objects you want to use. Add one or more of the following scopes to enable EWS access.
ews.messagesews.calendarsews.contacts
Connect an end user with EWS and Hosted authentication
- Send the end user to the Nylas Hosted auth login page by making a
GET /oauth/authorizerequest and specifying theproviderasews. - Have the end user log in using their Exchange account name and password, and if necessary, the server-specific details.
- Complete the auth flow by exchanging a token with the provider. The API response contains the grant ID for the end user, which you can use query for their data.
Using autodiscovery with Exchange
In most scenarios, end users can log in to Microsoft Exchange using their email address and password. This is because Nylas performs autodiscovery by default to determine the best server settings for the login attempt.
However, autodiscovery is sometimes unable to determine the correct settings. When this happens, the end user can enter more settings in the Advanced section of the login screen. If issues persist, the domain administrator can test the Exchange server's autodiscovery settings.
Log in using advanced settings
If autodiscovery is unavailable when an end user authenticates using Hosted auth, they must click Additional settings and enter information about the Exchange server.
- Enter the Exchange username, formatted as either
username@example.comorDOMAIN\username. This is usually the same as the end user's Windows login. - Enter the Exchange server address (for example,
mail.example.com). This address is usually visible in the Address bar when the end user logs in to the Outlook Web App.🔍 The end user might need to contact their Exchange or IT administrator to get the correct the connection settings.
Static IP support for Exchange on-prem accounts
Some email servers in secure environments only accept connections and data from a known list of sender IP addresses.
Support for connecting to Exchange on-prem using a static set of IP addresses is coming soon.
EWS limitations
- Nylas v3 currently supports self-hosted EWS instances using the
ewsprovider and Hosted Authentication. - If an account is accessible only through a corporate network, VPN, or firewall, you must allow Nylas to connect to the account.
- Be sure to turn on Exchange Web Services (EWS) and make it visible outside of the corporate network.
- Nylas uses EWS to fetch email messages and calendars for on-premises Exchange servers. If EWS isn't enabled, Nylas connects to the server using IMAP and fetches email messages only.
- If auto-discovery is available, Nylas attempts to use it. If it's not available, you must provide all settings information.
- If an end user has to enter their server settings information, Nylas can't use auto-discovery.
- The EWS server must support the Advanced Query Syntax (AQS) parser and have it enabled so Nylas can search and filter messages for users on that server.
App password required for two-factor authentication
If an end user has two-factor authentication (2FA) enabled for their account, they must generate an app password.
Exchange with private networks and VPNs
For an end user to connect, the Exchange server must not be in a private network or require a VPN to access it.
Unsupported EWS types
Nylas v3 supports Exchange on-prem only. Nylas cannot connect to Exchange services for Outlook, Microsoft 365 (previously Office 365), Live.com, or Exchange ActiveSync (EAS) accounts.
You can use the microsoft connector to authenticate Outlook, Microsoft 365, and Live.com users who are already using Microsoft Graph's modern OAuth system. Nylas doesn't support Exchange ActiveSync, and you cannot authenticate these accounts using EAS.