EWS Overview Tom Jebo Microsoft Open Specifications

Agenda What is EWS? Protocol Overview Autodiscover EWS Versioning EWS Operations Using EWS APIs Demo Resources and Tools

What is EWS? HTTP/SOAP based interface to Exchange Mailboxes EWS conversations require: HTTP GET/POST XML/SOAP When to use EWS? Alternative to MAPI (RPC or RPC/HTTP), intuitive/readable XML clients, admin functions, applications, web apps/services, e-Discovery. Benefits? Extensive command set and functionality access Includes modification of items Web-based (cross domains)

Clients Outlook OOF and Availability and new features Outlook for Mac (exclusively) Others: eM Thunderbird

Exchange and Protocol Versions Exchange support for EWS Started support in Exchange 2007 Previously in Exchange 2003, WebDAV was slower syncing. Currently support in Exchange 2013 as well as Exchange Online Protocol versions Versioned by schema for the SOAP bodies RequestServerVersion header element in each request Next slides for details…

Schema versions Archiving eDiscovery Personas Retention policies Unified Contact Store User photos Full access to items, folders, and attachments (Create, Get, Update, Delete) Availability Out of Office settings Notifications Synchronization Name resolution Distribution list (DL) expansion Search

RequestServerVersion header element <soap:Envelope xmlns:soap=" xmlns:xsi=" xmlns:xsd=" xmlns:soapenc=" xmlns:t="

ServerVersionInfo header element <h:ServerVersionInfo MajorVersion="15“ MinorVersion="1“ MajorBuildNumber="286“ MinorBuildNumber="24“ Version="V2_66" xmlns:h=" xmlns:xsd=" xmlns:xsi=" <m:GetRoomListsResponse ResponseClass="Success" xmlns:m=" … NoError

Schema versioning on a server Always messages.xsd and types.xsd in the virtual directory New version: Rename old version and include in new files with the base names CUs (rollups) now have EWS schema updates for Exchange Online. Schema file and version names are updated with SPs and releases in on-prem.

services.wsd l messages.x sd types.xsd For example, use svcutil.exe to generate code based on WSDL.

EWS Protocol Overview

EWS in Exchange Exchange Web Services in relation to the other protocols used by Exchange MS-OXPROTO 2.1

The Web Services Open Specifications for Exchange [MS-OXWSADISC] [MS-OXWSCDATA] [MS-OXWSXPROP] [MS-OXWSCORE] [MS-OXWSMSG] [MS-OXWSFOLD] [MS-OXWSCONT] [MS-OXWSMTGS] Etc.. [MS-OXPROTO] Types and Properties Operations on various items Configuration settings

Where to start? Autodiscover! What is it? Finds a URL for EWS calls Uses SMTP address and password Why use it? Topologies change, mailboxes move, URLs become outdated EWS fails (CAS) wrong URLs Alternative: hard code URLs MS-OXDISCO MS-OXDISCLI LDAP and DNS

What is the process? LDAP/DNS Finding an Autodiscover Server Autodiscover Finding an EWS URL EWS conversation Assumption: trustworthy Autodiscover URL (credentials sent) – HTTPS and valid certificate. Querying LDAP (serviceBindingInformation), DNS SRV (_service/_port), or HTTP redirection to find an autodiscover server. [MS-OXDISCO] has an overview. Query the Autodiscover server for a service endpoint (aka EWS server URL) to use. [MS-OXDSCLI] describes simple XML query like: /Autodiscover/Autodiscover.xml and /Autodiscover/Autodiscover.xml. [MS-OXWSADISC] describes SOAP-based query to URLs like: /autodiscover/autodiscover.svc /autodiscover/autodiscover.svc Finally, talk to the EWS server to authenticate the user and issue commands

Autodiscover example /exchange/autodiscover/outlook/responseschema/2006a

Autodiscover response example Tom Jebo /o=ExchangeLabs/ou=Exchange Administrative Group (FYDIBOHF23SPDLT)/cn=Recipients/cn=microsoft.onmicrosoft.com Tom Jebo e7908b08-1b ba7f-33677ce0cf32

settings True False EXHTTP outlook.office365.com On Basic ?path=/options/callanswering

Tracing Autodiscover in Outlook Ctrl + Shift + Right click on the task tray icon for Outlook Then select: “Test AutoConfiguration…”

Functional Overview of Protocol Review several of the functional groups Example of using EWS operations follows

Core Items and Data Types [MS-OXWSCORE]/[MS-OXWSDATA] Defines the base item operations and base types Get, Create, Move, Update, Delete, Copy, Send … are all defined here for the general case. Extended in other specs

message operations [MS-OXWSMSG] Operations: GetItem – ItemShape: IdOnly/AllProperties CopyItem – copies to a folder id, returns new id (new item) SendItem – send created message by item id CreateItem – specify item(s) and folder to save to MoveItem – no new id returned UpdateItem – item id, saveto id, field changes array. …

<RequestServerVersion Version="Exchange2012" xmlns=" <messages:GetItem xsi:type="messages:GetItemType" xmlns:xsi=" xmlns:xsd=" xmlns:types=" xmlns:messages=" IdOnly  [MS-OXWSCDATA] , AAMkADQ4NzFlNGQzLTE0MjctNDY1MS04MmY xLTkzZTJjOGE3Nzg5MQBGAAAAAACFZkYb4gNeRoKFg0vNFMECBwAR7Z LzvL8SS65OYqkrzuiyAAADWe9NAAC5/m6giL4oQqROGz5xBYbaAAJnUhTYAAA= [MS-OXWSCORE] Core Items Core Items Web Service Protocol

Folder operations [MS-OXWSFOLD] Operations: GetFolder – folder id and shape: properties CreateFolder – new child folder DeleteFolder – non-default folders EmptyFolder – deletes contained items & subfolders MoveFolder – everything moves with the folder … you get the idea! FolderId or DistinguishedFolderId [MS-OXWSCDATA] has the names enum “inbox” “contacts” “tasks” etc…

Appointments/Meetings and Contacts [MS-OXWSMTGS] and [MS- OXWSCONT] Operations: CopyItem UpdateItem CreateItem DeleteItem GetItem MoveItem Different semantics and properties for these but the same operations. CalendarItemTyp e ContactItemType

Searching for Folders and Items [MS-OXWSSRCH] Operations: FindFolder – get a list of subfolders based on “Restriction” FindItem – get an item in a folder(s) by Example on next slide…

AllProperties

NoError IPF.Note _tom … …

Data Xfer and Sync [MS-OXWSBTRF] ExportItems UploadItems <xs:element name="Data" type="xs:base64Bina ry " [MS-OXWSSYNC] SyncFolderHierarchy SyncFolderId

Availability operations [MS-OXWAVLS] GetUserAvailability – list of mailboxes to query free/busy options to query mtg suggestions options: max non-work hours results meeting duration etc…

<soap:Envelope xmlns:soap=" xmlns:xsi=" xmlns:xsd=" xmlns:soapenc=" xmlns:t=" urn:uuid:4BA B3-4B63-8EAE-C224FE79D8D9 … Organizer … [MS-OXWSAVLS] Availability Web Service Protocol

… T00:00: T00:00:00 30 MergedOnly 30 Poor T00:00: T00:00:00

DEMO: Example requests and responses Use EWSEditor to craft raw HTTP requests which would be called by the client. Then show these as examples. Let’s look at just a few examples for common requests like: 1.Finding folders 2.Getting mail items in a folder 3.Get a calendar appointment 4.Look up a contact

EWS Managed API

Overview of the API (just highlights) And Microsoft download API version 2.5 Requires.Net/C# or VB

DEMO:EWS Managed API in code example Take a look at some code examples using EWS Managed API.

javascript EWS in js (mail add-in only): Mailbox.makeEwsRequestAsync Only available in Outlook or mail add-ins General javascript apps: XmlHttpRequest object allows calls for raw HTTP POSTS Supported in many web browsers including IE General js code

Tools

EWSEditor This is your friend! Download: Log viewer Autodiscover viewer EWS POST

Message Analyzer Download free EWS Parsers: Tools | Asset Manager… search on Exchange Web Services Version 1.1 (January 2015) Demo: capture autodiscover, GetItem, FindItem

Fiddler Decrypts for you No parser Only shows HTTP(S) traffic HTTP/SOAP packets Demo with EWSEditor, Outlook, etc…

Netmon Parsers available Need unencrypted traffic using server cert Replaced by Message Analyzer Download and parsers: n/p/downloads.aspx Support and discussion: m/Forums/en- US/home?forum=netmon

References and resources

EWSEditor download Message Analyzer Fiddler EWS client design overview for Exchange Exchange EWS Test Suites