• Article

Using Exchange Impersonation (Exchange Web Services)

Topic Last Modified: 2007-10-31

Exchange Impersonation enables a caller to impersonate a given account so that the operations can be performed with the rights of the impersonated account, instead of the rights that are associated with the caller's account.

The ExchangeImpersonation SOAP header element provides the following three methods that you can use to identify the account to impersonate:

  • The user principal name (UPN) method
  • The Security Identifier (SID) method
  • The primary Simple Mail Transfer Protocol (SMTP) address method

To use the UPN to identify the account to impersonate

  • The PrincipalName element contains the fully qualified domain name (FQDN) for the location of the user account. This is not necessarily the user's mailbox domain. This element occurs as a child of the ConnectingSID element. Note that the UserPrincipalName attribute must be correctly stamped on the user account in the Active Directory directory service for the user lookup to succeed.

    <soap:Header>
  <t:ExchangeImpersonation>
    <t:ConnectingSID>
      <t:PrincipalName>User2@corp.example.com</t:PrincipalName>
    </t:ConnectingSID>
  </t:ExchangeImpersonation>
</soap:Header>

To use the user SID to identify the account to impersonate

  • The SID element contains the security identifier of the account to be impersonated. This is the security descriptor definition language (SDDL) form of the SID.

    <soap:Header>
  <t:ExchangeImpersonation>
    <t:ConnectingSID>
      <t:SID>S-1-5-21-1493619105-1843311271-3936346804-1118</t:SID>
    </t:ConnectingSID>
  </t:ExchangeImpersonation>
</soap:Header>

To use the primary SMTP address to identify the account to impersonate

  • The PrimarySmtpAddress element contains the primary SMTP address that is used to create the connecting SID.

    <soap:Header>
  <t:ExchangeImpersonation>
    <t:ConnectingSID>
      <t:PrimarySmtpAddress>User2@example.com</t:PrimarySmtpAddress>
    </t:ConnectingSID>
  </t:ExchangeImpersonation>
</soap:Header>

Example

The following example shows a request to impersonate another user and query the contents of the user's Inbox.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Header>
    <t:ExchangeImpersonation>
      <t:ConnectingSID>
        <t:PrincipalName>User2@example.com</t:PrincipalName>
      </t:ConnectingSID>
    </t:ExchangeImpersonation>
  </soap:Header>
  <soap:Body>
    <FindItem xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
                xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types"
                Traversal="Shallow">
      <ItemShape>
        <t:BaseShape>IdOnly</t:BaseShape>
      </ItemShape>
      <ParentFolderIds>
        <t:DistinguishedFolderId Id="inbox"/>
      </ParentFolderIds>
    </FindItem>
  </soap:Body>
</soap:Envelope>

Security

With Exchange Impersonation, one account is acting as another account. When an account is impersonated, the system logs the access as if the account that is specified in the header were acting on the system. The calling account must have the appropriate permissions to perform impersonation. For more information, see Configuring Exchange Impersonation (Exchange Web Services).