There has been some confusion about the different methods that can be used to access a mailbox. Developers are asking: What method should I use? When should I use it? What are the differences between the different methods? This post will give you a quick comparison of the two most common ways, other than a direct log on, to access a mailbox: Exchange Impersonation and delegate access.

Exchange Impersonation vs. Delegate Access

Exchange Impersonation is used in scenarios in which a single account needs to access many accounts. Line-of-business applications that work with mail typically use Exchange Impersonation. An application can be written to display mailbox data such as number of unread items, calendar, and so on. The application can use a dedicated service account to access multiple users’ mailboxes to display their respective data.

Exchange Impersonation is different than Windows Impersonation. Windows Impersonation is an operating system concept that requires you to set Kerberos constrained delegation. Exchange Impersonation is a simpler authorization mechanism that is designed for use only within Exchange Web Services (EWS). For more information about Windows Impersonation, see Client Impersonation on MSDN.

Delegate access is used in scenarios in which there needs to be a one-to-one relationship between users. One common application of delegate access is the sharing of calendars between users, such as when an admin manages an executive’s calendar, or a when handful of individuals working on a project need to coordinate calendars.

Another example of delegate access is resource mailbox management. Resources, such as conference rooms, can be managed by one or more people. Resources are represented by mailboxes, but not in the traditional sense. Resource mailboxes do not have owners; therefore, they can only be accessed by mail-enabled users to whom delegate access is granted.

The following table lists the differences between Exchange Impersonation and delegate access.

Administration

An administrator is able to configure impersonation on behalf of a service account, and grant that service account impersonation rights over many mailboxes. Individual users cannot manage who does or does not have impersonation rights over their mailboxes.

Individual users can grant and remove delegate access to their own mailboxes through several mailbox clients, such as Microsoft Outlook, Outlook Web Access, or Exchange Web Services-based clients. A mailbox owner does not need administrator rights to grant another user delegate access to their mailbox.

Auditing

There is no true auditing for either Exchange Impersonation or delegate access. Any mail that is modified by using impersonation will appear to the mailbox as if it was modified by the user who was impersonated. No log is left behind of the impersonation access.

^†For delegate access, there is partial auditing, in that any mail that is sent by a delegate on behalf of the mailbox owner is displayed as “Sent on behalf of.”

Usage

Exchange Impersonation can only be used through Exchange Web Services. The caller (authenticated user) indicates which user they want to impersonate in the SOAP header. For more information about how to use Exchange Impersonation, see Using Exchange Impersonation on MSDN.

Delegate access can be used through any mailbox client, including Outlook and Exchange Web Services-based clients. For more information about delegate access, see Exchange Web Services and Delegate Access on MSDN.

Rights

A user or account that has been granted impersonation rights will have the same rights as the user whom they are impersonating. Typically, service accounts are given the ability to impersonate the mailbox owner. In that case, the impersonating account has full mailbox rights, just as the mailbox owner does.

With delegate access, the delegate can be granted more granular rights, up to and including full mailbox access. Delegate access can also be configured per folder, or per mailbox. For example, a user can grant the delegate read-only access to the Inbox, read-write access to a calendar folder, and so on.

Configuration

Exchange Impersonation is generally configured as one-to-many: one service account to many user accounts. You can configure an account to impersonate a broad set of users, such as an entire mailbox database. For more information about how to configure impersonation, see Configuring Exchange Impersonation on MSDN.

For delegate access, there is no option to set up a single delegate for multiple mailboxes. A relationship must be established for each user who needs to access a given mailbox.

New Accounts

You can configure Exchange Impersonation to allow new accounts that are created to automatically be impersonated by service accounts. Setting up accounts to impersonate any user within a mailbox database can reduce your configuration overhead.

You must explicitly grant delegate access for any new users who are added.

Developing applications with Exchange Web Services just got MUCH easier, thanks to the release of the Microsoft Exchange Web Services (EWS) Managed API 1.0 Beta — a new managed-code API that's easy to learn, simple to use, and efficient to code against. Whether you're an experienced EWS developer, you’re new to Exchange development, or you’re somewhere in between, the EWS Managed API is made for you! Say goodbye to the large amounts of code and awkward patterns often required to use EWS via autogenerated proxy classes, and revel in the simplicity and efficiency of the new EWS Managed API!

Want to learn more? Check out David Claux's article Introducing the Exchange Web Services Managed API 1.0 for a full introduction to this new API. Take advantage of the conceptual material and code examples that are available in the Microsoft Exchange Web Services Managed API 1.0 Beta SDK April 2009. And keep your eye on this blog and the Exchange Developer Center in the coming months for posts and articles that explore various how-to scenarios for the EWS Managed API.

Using Exchange Web Services push notifications just got a lot easier, thanks to Exchange Server MVP Henning Krause. Henning has created a notification listener project on CodePlex. The listener application handles Exchange Web Services push notifications. The listener uses the WCF service model, and does not rely on IIS. Check it out, provide some feedback, and incorporate EWS push notifications into your Exchange Server client application.

Just a quick note to all you fans of MAPI out there. Based on some discussions we had a while ago, the folks in Office have been putting a LOT of time and effort into improving the MAPI material, and bringing it up-to-date for Office 2007. Well, they’ve finished their work, and the improvements are substantial! Check out the new content on MSDN Library at: http://msdn.microsoft.com/en-us/library/cc765775.aspx. We plan to have a redirection page under Exchange Server for about six months, to remind you where the stuff went.

Thom Randolph (thomr@microsoft.com)

We have just released update rollup 4 (RU4) for Exchange 2007 SP1.  This rollup fixes some bugs in Exchange Web Services (EWS), and introduces some behavior changes to EWS to allow customers and partners the flexibility to accomplish some key scenarios.  If you have written code against Exchange Web Services, we definitely recommend that you take a look at RU4. The following are the biggest changes that will be coming in the rollup:

-          Item IDs are now returned after MoveItem/CopyItem calls.

-          Unknown/unsupported item types are returned as Messages.

-          Updating tasks can now have correct behavior for Start and Complete Date values.

ItemId of Item Is Returned After a MoveItem/CopyItem Call

Some of our observant developers have noticed that Exchange creates new destination item IDs for items when they are moved between folders. We created a place in the schema to return the destination ID of an item, and in the early stages of Exchange development, this ID was returned. We pulled it out late in the Exchange 2007 development cycle after we determined that the method of determining the destination ID was too resource-intensive. After consistent feedback from customers that this feature was needed so that items could be tracked as they were moved between folders, we implemented a much more performant solution.  Now, if you call MoveItem/CopyItem, you’ll be able to identify the new item in the destination folder by looking at the destination ID that is returned by the MoveItem/CopyItem call.

Note: Cross-mailbox or mailbox-to-public folder CopyItem/MoveItem calls will not return destination IDs and RU4 must be applied to both the Client Access Server and the Mailbox Server Role for this feature to work.

Non-IPM.Note.* Items Are Returned as Messages

EWS in Exchange 2007 SP1 uses the <Item> type as the base class for items that are not strongly typed.  This design has caused problems for customers who want to reply to item types that have a custom item class, or item types that EWS does not yet support, like IPM.Sharing or IPM.InfoPath. In RU4, all item types that we do not support natively in Exchange Web Services, like Journal, Sharing Requests, InfoPath forms, are returned as <Message> instead of <Item>.  This means that you can see all the recipient information on the item, mark it as unread, reply to it, or forward it just like you would a normal item (assuming that the object supports forwarding/replying). 

<Item> type still exists as a base class for <Message>, so most applications built on the auto-generated proxy classes will not be affected; however, applications that parse the XML directly could break if they are expecting <Item> rather than <Message>. To minimize the risk of breaking applications, this behavior is only applied when the Exchange2007_SP1 version header is specified. 

We don’t take making changes in a rollup that could break applications lightly; our goal is to only change protocol behavior with the introduction of a new version header. However, we felt that this functionality is critical for some of our partners and customers, has a minimal impact on the majority of applications, is the way EWS should have worked in the first place, and can’t wait for the next service pack for Exchange, which could introduce a schema change for a new version header. For more details about this topic, see Robin’s June post that describes the proposed change and asks for feedback.

Updating Recurring Tasks Now Works Correctly

In Exchange 2007 and Exchange 2007 SP1, when a task is updated, such as by marking CompleteDate, the Client Access server shifts the date specified as the complete date according to the offset of its time zone. This is bad because clients are rarely aware of the time zone that the server is operating in. If the Client Access server and the client time zones are far enough apart, tasks could be marked as completed on the wrong day — not good!

The problem is that no time zone information is passed to EWS in tasks, yet a time zone is required when saving/updating/getting tasks to make sure that the task is marked as completed on the correct day. To fix this problem, with RU4, EWS can treat offset date times in a special way when they are the Complete Date, Due Date, or Start Date elements of a task. The offset, for example 10:00:00T-08:00, is used to create a time zone for that offset. This time zone is used when the task is saved so that the date the task was completed is always the date intended.

This post only covers the changes in RU4 that we think are most interesting to Exchange Web Services developers. We will be posting this and additional information in KB articles shortly. We hope you find this information useful and as always appreciate your feedback.

The Microsoft Exchange Server 2007 SP1 SDK has been updated and is now available for your coding pleasure! The Exchange 2007 SP1 SDK is available for download or viewable online. We suggest that you start with the What’s New page to learn about the updates made for the August release. So get rolling on your Exchange development projects with the latest version of the Exchange SDK! And while you’re at it, take some advice from the Autodiscover song.

The following proposal is a change that we’re considering for future Microsoft Exchange Server 2007 service packs and future releases of Exchange Server. Based on the feedback we’ve received, we have identified support for item classes, for which EWS doesn’t have a corresponding type, as one area where we can improve your experience with EWS. This proposed modification will change some of the default behavior, and before we make our final decision, we’d like to get your feedback.  If you are aware of any potential problems or existing coding patterns that would break as a result of this design change, please leave your comments below.
 
BACKGROUND:
When EWS returns an item that has an ItemClass that doesn’t map to a strong type, it returns that item as an ItemType.  For example, a developer could choose to store an item with a custom item class (i.e. “Item.Custom”) in Exchange. Because EWS doesn’t have a strong type for “Item.Custom”, the item would be returned as an ItemType.  These items create problems for EWS developers because ItemType objects cannot be sent by using the SendItem method. These items cannot be sent because they lack a number of key properties – i.e. ToRecipients, CcRecipients, Sender, and so on. Another issue developers have when working with these items is that there is no way to mark them as Read/Unread. The potential solution we’ve come up with is to have EWS return these items as messages.

The MessageType derives from ItemType, so developers would gain new methods and functionality and there would be no loss of existing functionality with this solution. Exposing these additional properties would enable developers to Send, Reply, ReplyAll, and Forward these items as well as mark them as Read/Unread.

Existing code that creates an ItemType will continue to work by using the proxy objects or XML, but those same items would be returned (via FindItem or GetItem) as MessageType objects. For these MessageType objects, you would need to look at the associated ResponseObjects property to see if Reply or ReplyAll is allowed. For example, with this change, we would return a non-delivery report (NDR) as a MessageType.  You would be allowed to forward it, but it doesn’t make sense to Reply or ReplyAll to an NDR.

SAMPLE CODE USING PROXY OBJECTS:
If you are using the auto-generated proxy objects, you shouldn’t notice any changes. One exception to this would be if your code is explicitly checking the item type that is returned. Because MessageType derives from ItemType, you would still be able to treat the returned item as an ItemType even though it is a MessageType.

GetItemType getRequest = new GetItemType();
getRequest.ItemIds = new BaseItemIdType[] { createResponseMessage.Items.Items[0].ItemId };
getRequest.ItemShape = new ItemResponseShapeType();
getRequest.ItemShape.BaseShape = DefaultShapeNamesType.AllProperties;

GetItemResponseType getItemRespone = esb.GetItem(getRequest);
ItemInfoResponseMessageType getItemResponeMessage = getItemRespone.ResponseMessages.Items[0] as ItemInfoResponseMessageType;

// If your existing application has this line of code, it will keep working regardless of whether the item coming back is an item or a message.
ItemType returnedItem = getItemResponeMessage.Items.Items[0];

// If you wanted to take advantage of the enhanced behavior, you would now be able to cast these items (for which we don’t have a strong type) as message.
MessageType returnedItem = (MessageType)getItemResponeMessage.Items.Items[0];

SAMPLE CODE USING XML: 
The biggest change would be for developers who are sending/receiving raw XML and parsing specific nodes.  The following code will not work after this change.

XmlNamespaceManager namespaceManager = new XmlNamespaceManager(new NameTable());
namespaceManager.AddNamespace("t", @"http://schemas.microsoft.com/exchange/services/2006/types");
namespaceManager.AddNamespace("m", @"http://schemas.microsoft.com/exchange/services/2006/messages");
namespaceManager.AddNamespace("soap", @"http://schemas.xmlsoap.org/soap/envelope/");
 
XmlDocument response = new XmlDocument();
int xmlStartIndex = responseText.IndexOf("<?xml");
response.LoadXml(responseText.Substring(xmlStartIndex));
string xPath = string.Format(@"//t:Items/t:Item/t:Subject[text()='{0}']", "MySubject");
XmlNodeList nodeList = response.SelectNodes(xPath, namespaceManager);

After the proposed change, response.SelectNodes would not find a children of “Items” called “Item” and therefore nodeList.Count will be 0. The XPath query would need to be updated to:
string xPath = string.Format(@"//t:Items/t:Message/t:Subject[text()='{0}']", "MySubject");

SERVER VERSIONS:
This proposed change will only affect requests that set the Version attribute of the RequestServerVersion SOAP header to Exchange2007_SP1. Requests made with the Version attribute set to Exchange2007, or requests where no RequestServerVersion SOAP header was specified, will continue to return these items as ItemType objects.

EXISTING BEHAVIOR:
  <m:GetItemResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
     <m:ResponseMessages>
       <m:GetItemResponseMessage ResponseClass="Success">
         <m:ResponseCode>NoError</m:ResponseCode>
         <m:Items>
           <t:Item>
             <t:ItemId Id="..." ChangeKey=".."/>
             <t:ParentFolderId Id="..." ChangeKey="..."/>
             <t:ItemClass>ABC.DEF</t:ItemClass>
             <t:Subject>This is an ItemClass which EWS doesn’t have a strong type</t:Subject>  

     ...     
          </t:Item>
         </m:Items>
       </m:GetItemResponseMessage>
     </m:ResponseMessages>
   </m:GetItemResponse>

PROPOSED BEHAVIOR:
  <m:GetItemResponse xmlns:m="http://schemas.microsoft.com/exchange/services/2006/messages" xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
     <m:ResponseMessages>
       <m:GetItemResponseMessage ResponseClass="Success">
         <m:ResponseCode>NoError</m:ResponseCode>
         <m:Items>
           <t:Message>
             <t:ItemId Id="..." ChangeKey=".."/>
             <t:ParentFolderId Id="..." ChangeKey="..."/>
             <t:ItemClass>ABC.DEF</t:ItemClass>
             <t:Subject>This is an ItemClass which EWS doesn’t have a strong type</t:Subject>
            ...
            <t:ConversationIndex>AQHIueIXa5lWW0xw20qwVRcT611b/Q==</t:ConversationIndex>
             <t:ConversationTopic>ABC.DEF</t:ConversationTopic>
             <t:InternetMessageId>&lt;E4D3FFFB356BA34FAD06F517E1AECCE711C41DB278@Server.company.com&gt;</t:InternetMessageId>
             <t:IsRead>true</t:IsRead>
           </t:Message>
         </m:Items>
       </m:GetItemResponseMessage>
     </m:ResponseMessages>
   </m:GetItemResponse>

We think we’ve thought through most of the common scenarios for how people are using EWS, but this community is a rich source of customer experiences. If you are aware of any cases where this design change would cause problems, we want to know about it. Please leave your questions or comments below.

The following interfaces and properties are defined in the Exchange header file edkmdb.h. They are provided here in case your application has to use them, and you are unsure of their function.

Applications implement interfaces according to the IExchangeImportContentsChanges definition. The interface that is used by the Incremental Change Synchronization (ICS) system can notify the application when changes to the mailbox content have occurred. The interface is registered for callback when you configure the synchronizer object that is returned by the MAPI folder object.

The interface definition is commented-out in the header file edkmdb.h because Exchange does not actually implement the interface. The application implements the interface.

// IExchangeImportContentsChanges
    STDMETHOD(GetLastError)(HRESULT hResult, ULONG ulFlags, __in LPMAPIERROR *lppMAPIError);
    STDMETHOD(Config)(__in LPSTREAM lpStream, ULONG ulFlags);
    STDMETHOD(UpdateState)(__in LPSTREAM lpStream);
    STDMETHOD(ImportMessageChange)
        (ULONG cpvalChanges, __in LPSPropValue ppvalChanges, ULONG ulFlags, __in LPMESSAGE *lppMessage);
    STDMETHOD(ImportMessageDeletion)(ULONG ulFlags, __in LPENTRYLIST lpSrcEntryList);
    STDMETHOD(ImportPerUserReadStateChange)(ULONG cElements, __in LPREADSTATE lpReadState);
    STDMETHOD(ImportMessageMove)
        (ULONG cbSourceKeySrcFolder, __in BYTE *pbSourceKeySrcFolder,
         ULONG cbSourceKeySrcMessage, __in BYTE *pbSourceKeySrcMessage,
         ULONG cbPCLMessage, __in BYTE *pbPCLMessage,
         ULONG cbSourceKeyDestMessage, __in BYTE *pbSourceKeyDestMessage,
         ULONG cbChangeNumDestMessage, __in BYTE *pbChangeNumDestMessage)

The following interface definition, found in the edkmdb.h header file, is returned by the MAPI folder object. Configure the object properties using the object methods, and then call the Synchronize method to register the custom ExchangeImportContentsChanges callback routine of your application.

#define EXCHANGE_IEXCHANGEEXPORTCHANGES_METHODS(IPURE)      \
    MAPIMETHOD(GetLastError)                                \
       (THIS_ HRESULT hResult,                              \
        ULONG ulFlags,                                      \
        LPMAPIERROR FAR * lppMAPIError) IPURE;              \
    MAPIMETHOD(Config)                                      \
       (THIS_ LPSTREAM lpStream,                            \
        ULONG ulFlags,                                      \
        LPUNKNOWN lpUnk,                                    \
        LPSRestriction lpRestriction,                       \
        LPSPropTagArray lpIncludeProps,                     \
        LPSPropTagArray lpExcludeProps,                     \
        ULONG ulBufferSize) IPURE;                          \
    MAPIMETHOD(Synchronize)                                 \
       (THIS_ ULONG FAR * lpulSteps,                        \
        ULONG FAR * lpulProgress) IPURE;                    \
    MAPIMETHOD(UpdateState)                                 \
       (THIS_ LPSTREAM lpStream) IPURE;
#undef INTERFACE

The PR_CONTENTS_SYNCHRONIZER property is used to request a pointer to the IExchangeExportChanges object. Note that the PT_Object and PROP_TAG are also defined in the edkmdb.h header file.

#define pidStoreMin 0x6618
#define PR_CONTENTS_SYNCHRONIZER PROP_TAG( PT_OBJECT, pidStoreMin+0x15)

The following flags instruct ICS as to what types of changes the application is interested in receiving.

/*------------------------------------------------------------------------
 *
 *     Flags used by Exchange Incremental Change Synchronization Interface
 *
 *-----------------------------------------------------------------------*/
#define SYNC_UNICODE                         0x01
#define SYNC_NO_DELETIONS                    0x02
#define SYNC_NO_SOFT_DELETIONS                   0x04
#define SYNC_READ_STATE                      0x08
#define SYNC_ASSOCIATED                      0x10
#define SYNC_NORMAL                          0x20
#define SYNC_NO_CONFLICTS                    0x40
#define SYNC_ONLY_SPECIFIED_PROPS            0x80
#define SYNC_NO_FOREIGN_KEYS                 0x100
#define SYNC_LIMITED_IMESSAGE                0x200
#define SYNC_CATCHUP                         0x400
#define SYNC_NEW_MESSAGE                     0x800 // only applicable to ImportMessageChange()
#define SYNC_MSG_SELECTIVE                   0x1000 // Used internally. Will reject if used by clients.
#define SYNC_BEST_BODY                       0x2000
#define SYNC_IGNORE_SPECIFIED_ON_ASSOCIATED  0x4000
#define SYNC_PROGRESS_MODE                   0x8000 // AirMapi progress mode
#define SYNC_FXRECOVERMODE                   0x10000
#define SYNC_DEFER_CONFIG                    0x20000
#define SYNC_FORCE_UNICODE                   0x40000 // Forces server to return Unicode properties

When combined with the others defined in the ebkmdb.h, the following bit-field definitions are used to indicate the scope of changes that Exchange ICS will report to the application:

#define CONVENIENT_DEPTH  ((ULONG) 0x00000001
#define SHOW_SOFT_DELETES ((ULONG) 0x00000002)
#define SHOW_SUBFOLDERS   ((ULONG 0x00000004)

The PR_LOCAL_COMMIT_TIME_MAX property, which is returned for a folder, indicates when any items in the folder were last changed. When this property value is different from the PR_LOCAL_COMMIT_TIME property value, items in the folder have changed since the last time changes to the folder were committed to the database.

#define pidAdminMin 0x6690
#define PR_LOCAL_COMMIT_TIME_MAX PROP_TAG(PT_SYSTIME, pidAdminMin+0x7a)

The PR_DELETED_COUNT_TOTAL property indicates how many items have been deleted from the folder since the folder was created.

#define pidAdminMin 0x6690
#define PR_DELETED_COUNT_TOTAL PROP_TAG(PT_LONG, pidAdminMin+0x7b)