Security and Impersonation

banner art

The Microsoft CRM 3.0 SDK uses best practices as defined by the Microsoft .NET Framework to impersonate a user. These best practices suggest that the security related information be passed in implicitly as part of the SOAP headers. As a result, unlike APIs used in the earlier 1.x versions of the SDK, userAuth is no longer included as the first parameter in the method signatures. Instead, a technique known as impersonation is used.

Impersonation is used to execute business logic (code) on behalf of a Microsoft CRM user in order to provide a desired feature or service. This is necessary because the Microsoft CRM Web services can be called by various clients as well as services that access Microsoft CRM SDK on behalf of a Microsoft CRM user. An example of such a client or service would be a workflow or custom ISV solution.

To use impersonation, the user account under which the impersonation code is to run must be added to the PrivUserGroup in Microsoft Active Directory. This group is created by Microsoft CRM during installation and setup. This user account need not be associated with a licensed Microsoft CRM user. However, the user that is being impersonated must be a licensed Microsoft CRM user.


The following code example shows how to use impersonation when accessing a Web service.

CrmService myService = new CrmService();
myService.Url = "http://localhost/mscrmservices/2006/crmservice.asmx";

// Pass in a value for the SOAP Header attribute.
// This is the user that I want to impersonate.
myService.CallerIdValue = new CallerId();
myService.CallerIdValue.CallerGuid =new Guid("2B951FBC-1C56-4430-B23B-20A1349068F3");

// Set the network credentials to that of the current process.
// The user account under which the process is executing must exist in
// PrivUserGroup.
myService.Credentials = System.Net.CredentialCache.DefaultCredentials;

In the above example, the CallerIdValue.CallerGuid must be set to the GUID of a Microsoft CRM user. This user should have sufficient Microsoft CRM security privileges to take the action you are requesting, such as creating or updating an account. This user should not have the Restricted Access Mode check box marked on the User form. The Restricted Access Mode check box will restrict the actions a user can perform regardless of the roles assigned to them. You can find this setting in Microsoft CRM by selecting Settings, point to Business Unit Settings, click Users, and open the User form for the target user.

In the example code, the user account under which the code executes has been added to the PrivUserGroup. As a result, the default network credentials can be used. If the user account has not been added to PrivUserGroup, you must explicitly specify the network credentials of an account that is in PrivUserGroup as shown below. Substitute the appropriate login information for the user name, password, and domain.

myService.Credentials =
new NetworkCredential("PrivUserName","PrivUserPassword","PrivUserDomain")

© 2007 Microsoft Corporation. All rights reserved.