# Authenticating Exchange on-premises accounts with Nylas Source: https://developer.nylas.com/docs/provider-guides/exchange-on-prem/ You can use the Nylas EWS connector to connect to email accounts hosted on Exchange on-prem servers so you can use the Nylas Email, Calendar, Contacts, and Notetaker APIs with them. > **Warn:** > **Microsoft announced the [retirement of Exchange Web Services in 2022](https://techcommunity.microsoft.com/t5/exchange-team-blog/retirement-of-exchange-web-services-in-exchange-online/ba-p/3924440) and strongly recommended that [all users migrate to use Microsoft Graph](https://techcommunity.microsoft.com/t5/exchange-team-blog/ews-exchange-web-services-to-microsoft-graph-migration-guide/ba-p/3957158).** 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](#using-autodiscovery-with-exchange) 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 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](/docs/reference/api/connectors-integrations/create_connector/), 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: 1. In the Nylas Dashboard, navigate to the application you want to use EWS with. 2. Click **Connectors** in the left navigation. 3. Find the EWS item, and click the plus icon (**+**). 4. 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.messages` - `ews.calendars` - `ews.contacts` ## Connect a user with EWS and Hosted authentication 1. Send the user to the Nylas Hosted auth login page by making a [`GET /v3/connect/auth` request](/docs/reference/api/authentication-apis/get_oauth2_flow/) and specifying the `provider` as `ews`. 2. Have the user log in using their Exchange account name and password, and if necessary, the server-specific details. 3. Complete the auth flow by [exchanging a token with the provider](/docs/reference/api/authentication-apis/exchange_oauth2_token/). The API response contains the grant ID for the user, which you can use query for their data. ## Using autodiscovery with Exchange In most scenarios, users can log in to Microsoft Exchange using their email address and password. This is because Nylas performs [autodiscovery](https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/autodiscover-for-exchange) 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 user can [enter more settings in the Advanced section](#log-in-using-advanced-settings) of the login screen. If issues persist, the domain administrator can [test the Exchange server's autodiscovery settings](https://testconnectivity.microsoft.com/). ### Log in using advanced settings If autodiscovery is unavailable when a user authenticates using [Hosted auth](/docs/provider-guides/microsoft/authentication/), they must click **Additional settings** and enter information about the Exchange server. 1. Enter the **Exchange username**, formatted as either `username@example.com` or `DOMAIN\username`. This is usually the same as the user's Windows login. 2. Enter the **Exchange server** address (for example, `mail.example.com`). This address is usually visible in the Address bar when the user logs in to the Outlook Web App. > **Info:** > **The user might need to contact their Exchange or IT administrator to get the correct the connection settings**. ![The Microsoft Exchange login page showing the "Advanced Settings" options.](/_images/microsoft/exchange-login-advanced-settings.png "Exchange advanced 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 IP addresses. If you're on a contract plan, you can use [static IP routing](/docs/dev-guide/platform/#static-ips) to connect to an Exchange on-prem server. ## Message IDs and folder moves (Microsoft Exchange via EWS) For Microsoft Exchange mailboxes accessed via the Exchange Web Services (EWS) protocol, message IDs can change when a message is moved between folders. This is expected Exchange behavior. This applies to Exchange on-premise servers which will have grants of type `exchange`. This **does not apply** to mailboxes hosted by Exchange Online, or hybrid Exchange servers as we use **Microsoft Graph instead of EWS**. Grants that use Microsoft Graph instead of EWS will be of type `microsoft`. Because of this, **Nylas message IDs for Microsoft accounts should be treated as folder-specific pointers, not permanent identifiers**. If you need to track a message across folder moves, use the `InternetMessageId` (RFC `Message-ID` header) instead. This value remains stable across moves. To get the `InternetMessageId`, [include headers in your message requests](/docs/v3/email/headers-mime-data/) by setting the `fields` query parameter. On EWS, `fields=include_basic_headers` is the recommended option — it returns `Message-ID`, `In-Reply-To`, and `References` reliably across the board, whereas `fields=include_headers` only returns headers Nylas generates for MIME on EWS (provider limitation). > **Info:** > **Multiple messages can share the same `InternetMessageId`**. Exchange allows copies of a message to exist in multiple folders, all with the same `InternetMessageId`. If you need to distinguish between copies (for example, in compliance or auditing scenarios), you should track both the `InternetMessageId` and the folder location. ## EWS limitations - Nylas currently supports self-hosted EWS instances using the `ews` provider 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 messages and calendars for on-premises Exchange servers. If EWS isn't enabled, Nylas connects to the server using IMAP and fetches messages _only_. - If auto-discovery is available, Nylas attempts to use it. If it's not available, you must provide all settings information. - If a user has to enter their server settings information, Nylas can't use auto-discovery. - The EWS server must support the [Advanced Query Syntax (AQS)](https://learn.microsoft.com/en-us/windows/win32/lwef/-search-2x-wds-aqsreference) 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 a user has two-factor authentication (2FA) enabled for their account, they must [generate an app password](https://support.microsoft.com/en-us/help/12409/microsoft-account-app-passwords-two-step-verification). ### Exchange with private networks and VPNs For a user to connect, the Exchange server must not be in a private network or require a VPN to access it. ### Unsupported EWS types Nylas 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.