Share via

MAPI and Impersonation

  • Article

There is an article which you used to be able to find at https://support.microsoft.com/kb/259301. This article, which I helped to write, walked you through the mechanics of impersonating a user before using MAPI. I pulled this article recently and just wanted to discuss briefly why.

There are three main problems with doing impersonation and then using MAPI: registry access, support threads, and instance data.

Registry Access

The first problem is that MAPI wants to use HKEY_CURRENT_USER to access the registry for profiles. This works fine for any thread running as the same user that the process was run as. However, the predefined HKEY_CURRENT_USER handle, which MAPI uses, will always point to the registry hive of the process' user, not the thread's user. There is a trick (this article was pulled due to the problems described below) to substitute a different registry hive which works if you have full control of all code accessing the registry, but this is rarely true of most applications.

There's another trick to avoiding these registry problems: MAPI_TEMPORARY_PROFILES. This flag causes MAPI to use file based profiles instead of using the registry. However, support for this flag was removed in Outlook 2003, so this trick can only be used with Exchange's MAPI and older versions of Outlook.

Support Threads

Both Outlook's and Exchange's implementations of MAPI depend on several support threads which they will spin up in the course of normal operations. Outlook's MAPI uses support threads for it's implementation of Cancel RPC, and both use support threads to handle notification processing (even when the client has not specifically requested notifications). MAPI creates these new threads using CreateThread. Note that the documentation for CreateThread specifically states that this API should not be used from a thread running under impersonation.

If you're using Exchange's MAPI, then there is a way to switch to a different notification engine which doesn't suffer from as many of these problems. It's documented in XCLN: OWA Clients Receive a "Failed to Connect to the Microsoft Exchange Server" Error Message (323872). Note that the article mentions reg keys such as inetinfo and dllhost. These reg keys would need to be the name of your application in order to work.

Instance Data

MAPI stores “instance data” for each security context that calls MAPIInitialize. The information includes the heap handles, shared sections for interacting with other processes using the same security context, etc.  Instance data lives in a structure that is keyed to a hash of the current security context’s SID. So, if you create a MAPI object under one security context and release it under another, MAPI either a) fails to find the instance data and crashes, or b) frees the object from the wrong heap and corrupts the heap. How this instance data is affected by impersonation was also involved in the Deleted Profile issue.

Observed Problems

We've seen a number of crashes in code that uses impersonation and then uses MAPI. Many of these relate to heap allocations occurring with one user context and then the deallocations happening with another context. Both the Exchange and Outlook development teams are aware of these issues. However, especially due to the problem with CreateThread, we've not been able to fix all of them.

Update

I had originally stated "Other problems we have seen, especially in code that manipulates profiles prior to logon is OpenMsgStore failing with MAPI_E_FAILONEPROVIDER (0x8004011D) and MAPI_E_NETWORK_ERROR (0x80040115)." After further investigation, it turns out the code that was seeing these problems was creating the profiles by editing MAPISVC.INF, and these file manipulations were not protected properly by a mutex. So one thread's edits of the file were overwritten by another thread's edits before the profile could be configured. Subsequent failures in MAPI were then due to the corrupted profiles.

Workarounds

If you're using impersonation in order to access multiple mailboxes, you may be doing too much work. You can use IExchangeManageStore::CreateStoreEntryID to log on to any mailbox for which you have the appropriate permissions. So for code running under an administrator account with the right permissions, you can use this API to access any mailbox without doing any impersonation.

If you must do impersonation, for example, to connect to different servers where it may not be possible to arrange a single account with the right permissions, then the recommendation is to use a stub program to impersonate, then call CreateProcessAsUser to launch your worker program which does the real MAPI work.

Conclusions and Recommendations

Getting MAPI to work with impersonation is very hard. If you have an application which uses MAPI with impersonation and you're not experiencing problems, congratulations. If you're planning on writing new MAPI code and you think you need to use impersonation, follow one of the above workarounds. I pulled the article (which did nothing more than walk through the mechanics of using LogonUser and leak at least two handles along the way) so as not to encourage new code using MAPI under impersonation.

If you absolutely must use impersonation with MAPI:

  • Use Exchange's MAPI. Outlook does not support impersonation with MAPI at all.
  • Use MAPI_TEMPORARY_PROFILES and create your profiles manually
  • On each thread where you do impersonation, all impersonation code must happen before MAPIInitialize
  • Use the notification engine from 323872
  • Never share MAPI objects across different security contexts.

Thanks to Dana Birkby and others for reviewing this article.

[Edit - 4/22/05 - 9:30AM - Updated Observed Behavior section]

[Edit - 7/19/05 - 5:35PM - Noted that KB 199190 was pulled]

Comments

  • Anonymous
    July 01, 2005
    Thank you for posting this information. I do have a couple of questions:

    - Will MAPI_TEMPORARY_PROFILES work with the MAPI subsystem with the Exchange 5.5 Administrator install?

    - If MAPIInitialize does work at the thread context level, why can't I call it BEFORE ImpersonateLoggedOnUser? For example, I want to be able to use the same thread for two different users' operations (sequentially). Do I need to MAPIInitialize one time for both, or MAPIInitialize after impersonation each time? Can you clarify "all impersonation code must happen before MAPIInitialize"?

    - I wouldn't think that CreateProcessAsUser would be recommended for a server side application. One process for every user accessing the store?
  • Anonymous
    August 08, 2005
    I believe MAPI_TEMPORARY_PROFILES will work with 5.5.

    When you call MAPIInitialize, MAPI creates a new thread using the CreateThread API. This is the heart of the problem. Supposing you want to work sequentially, I would recommend:
    Impersonate
    MAPIInit
    DoWork
    MAPIUninit
    UnImpersonate
    Repeat for next user.

    BUT - I wouldn't really recommend doing this at all. It's safer to spin off a new process.

    CreateProcessAsUser: Yes - one per user is exactly what I'm recommending. Of course, you should examine your architecture to see if you can consolidate your users. For example - a single administrative user with the right access rights can access everybody's mailbox - no need for impersonation.
  • Anonymous
    August 15, 2005
    Thank you so much for clarifying. Would there be any memory leak issues when calling MAPIInit/MAPIUninit so often (for every operation)?
  • Anonymous
    August 15, 2005
    Thanks for the clarification. One more question - are there any known memory implications of the MAPIInit/MAPIUninit for each operation (i.e. any persistent leaks)?
  • Anonymous
    August 16, 2005
    The comment has been removed
  • Anonymous
    November 23, 2005
    Hi, Steve,

    I'm using CreateProcessAsUser (under userA) to spin off the MAPI worker program (under userB), as mentioned in your workaround section.

    But sometimes I find the worker program cannot access userB's HKCU. However, when I logon as userB and run the worker program, it's OK. (both userA and userB are local admins)

    I'm wondering if I need to something extra before launching the worker program?

    Thanks
    George
  • Anonymous
    November 23, 2005
    George,
    From the MSDN docs on CreateProcessAsUser:
    CreateProcessAsUser does not load the specified user's profile into the HKEY_USERS registry key. Therefore, to access the information in the HKEY_CURRENT_USER registry key, you must load the user's profile information into HKEY_USERS with the LoadUserProfile function before calling CreateProcessAsUser. Be sure to call UnloadUserProfile after the new process exits.

    Steve
  • Anonymous
    December 14, 2005
    The comment has been removed
  • Anonymous
    December 15, 2005
    Pritesh,
    From a security perspective, I cannot imagine a scenario where using impersonation from your service is a better alternative than just granting the service account access to the mailbox. Consider what would happen if your service was comprimised. If it has access to the mailboxes, the worst it could do is damage the mailboxes. On the other hand, if it's impersonating the users, it could do anything those users have permission to do. Clearly the first scenario is preferable.

    I would advise you to revisit your restriction.

    Steve
  • Anonymous
    April 24, 2006
    I am trying to expand a personal distribution list in the user's Contacts folder from a COM app server called from an IIS ISAPI extension.  The COM object runs in an admin account which has a mailbox.

    Heeding your warning about impersonation, I am using HrMailboxLogon which gives me access to the user's mailbox but not the Contacts folder.  I think the entryID may be incorrect.

    Any ideas?
  • Anonymous
    April 24, 2006
    Sorry, I meant to say that I found this blog really useful.
  • Anonymous
    May 21, 2006
    Hi Steve,
    In this blog you said "Other problems we have seen, especially in code that manipulates profiles prior to logon is OpenMsgStore failing with MAPI_E_FAILONEPROVIDER (0x8004011D)" and also you have told that this is due to "editing MAPISVC.INF file and these file manipulations were not protected properly by a mutex".

    So in this context can i know do we have any fix addressing the above issues .... ( i meant is it available in any of the recent SP's )

    ~ Gokul
  • Anonymous
    May 22, 2006
    Gokul - there's nothing in MAPI to fix for that - MAPISVC.INF is a text file and the API's used to modify it are not part of MAPI.

    I wouldn't recommend editing MAPISVC.INF for the purposes of creating a profile anyway, but if you're going to do that, you need to make sure you don't have another thread trying to create a profile running at the same time. Otherwise, you're likely to be creating a profile with a MAPISVC.INF that's in a half edited state.