MAPI and Impersonation


There is an article which you used to be able to find at http://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 (13)

  1. Nate Cole says:

    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?

  2. Stephen Griffin says:

    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.

  3. Nate Cole says:

    Thank you so much for clarifying. Would there be any memory leak issues when calling MAPIInit/MAPIUninit so often (for every operation)?

  4. Nate Cole says:

    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)?

  5. Stephen Griffin says:

    Interesting you should mention that. There are actually a couple known memory leaks with MAPIInit/MAPIUninit and Exchange 2003.

    One which we have a hotfix for is this:

    http://support.microsoft.com/kb/891509

    Note that in order for that fix to be effective, you have to set the CleanUpMAPIHeap key, which has the potential of breaking any Simple MAPI applications on the box. (I need to blog about the ‘why’ on that later.)

    With that fix in place, you’ll still have a critical section and a heap leak. We’re working on fixes for those. I’ll try to remember to post the fix here when they’re ready.

  6. wzhao2000 says:

    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

  7. Stephen Griffin says:

    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

  8. Pritesh Suvarna says:

    Thanks for your article.

    We are using a Windows service which should Logon to the Exchange server, read mails and store it.

    The Windows service is expected to access more than 1 mail box on the Exchange server.

    We are using MAPI to acheive this.

    The restriction here is that the Service user cannot have access to the mailboxes on the Exchange server, so we have to use Impersonation.

    But when we use Impersonation, the Impersonation is successful (the Windows Identity changes to the impersonated user), but the Logon of MAPI session fails.

    Your article says about updating the HK_Current_User with the profile of the user.

    And also talks about updating the MAPI_TEMPORARY_PROFILES.

    Is there any sample code , on how to acheive the same.

    Thanks.

  9. Stephen Griffin says:

    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

  10. mikec says:

    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?

  11. mikec says:

    Sorry, I meant to say that I found this blog really useful.

  12. Gokul says:

    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

  13. Stephen Griffin says:

    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.