Impersonation in Plug-ins

Impersonation is used to execute business logic (code) on behalf of a Microsoft Dynamics CRM system user to provide a desired feature or service for that user. Microsoft Dynamics CRM obtains the pre-entity and post-entity images that are passed to plug-ins in the execution context on behalf of the impersonated system user. Any business logic executed within a plug-in, including Web service method calls, is governed by the security privileges of the impersonated user.

Plug-ins execute under the security account, which is specified on the Identity tab of the CRMAppPool Properties dialog box. The dialog box can be accessed by right-clicking the CRMAppPool application pool in Internet Information Services (IIS) Manager and then clicking Properties in the shortcut menu. By default,CRMAppPool uses the Network Service account identity. If the CRMAppPool identity is changed to a system account other than Network Service, the new identity account must be added to the PrivUserGroup group in Active Directory.

The two methods that can be employed to impersonate a user are discussed in the next two topics.

Impersonation during plug-in registration

One method to impersonate a system user within a plug-in is by specifying the impersonated user during plug-in registration. When registering a plug-in, if theimpersonatinguserid field of the sdkmessageprocessingstep or SdkMessageProcessingStepRegistration class instance is set to a specific Microsoft Dynamics CRM system user, Web service calls made by the plug-in execute on behalf of the impersonated user. If the impersonatinguserid field is set to a value of null orGuid.Empty during plug-in registration, the calling/logged on user or the standard "system" user is the impersonated user.

Whether the calling/logged on user or "system" user is used for impersonation is dependent on the request being processed by the pipeline and is beyond the scope of the SDK documentation. For more information about the "system" user, refer to the next topic.

Impersonation during plug-in execution

Impersonation that was defined during plug-in registration can be altered in a plug-in at run time. Even if impersonation was not defined at plug-in registration, plug-in code can still use impersonation. The following discussion identifies the key properties and methods that play a role in impersonation when making Web service method calls in a plug-in.

The platform passes the impersonated user ID to a plug-in at run time through the IPluginExecutionContext.UserId property. The UserId property can have one of three different values as shown in the table below.

UserId Value
Condition

Initiating user

or

"system" user

The impersonatinguserid property of the sdkmessageprocessingstep or SdkMessageProcessingStepRegistration class instance is set to null orGuid.Empty at plug-in registration.

Impersonated user
The impersonatinguserid property is set to a valid system user ID at plug-in registration.

"system" user
The current pipeline was executed by the platform, not in direct response to a Web service method call.

If you specify an impersonated user during plug-in registration, you should set up the Web service proxy in the plug-in by passing a value of true to theCreateCrmService method or the CreateMetadataService method. Passing a value of true indicates to use the ID in the IPluginExecutionContext.UserId property as the impersonated user. The following code example shows how to do this.

Example

[C#] ICrmService service = context.CreateCrmService(true);

This is equivalent to the following code:

Example

[C#] ICrmService service = context.CreateCrmService(context.UserId);

To ignore any impersonating user set during plug-in registration, use the following code.

Example

[C#] ICrmService service = context.CreateCrmService(false);

When a value of false is passed to the CreateCrmService method or the CreateMetadataService method, the platform uses the built-in "system" account to execute Web service method calls made by your plug-in code. The "system" account is a high privilege user account with some restrictions. For example, the "system" account cannot create a task activity.

The InitiatingUserId property of IPluginExecutionContext contains the ID of the system user that called the Web service method that ultimately caused the plug-in to execute. The following code shows how to create a Web service proxy to make Web method calls on behalf of the initiating user.

Example

[C#] ICrmService service = context.CreateCrmService(context.InitiatingUserId);

If the impersonatinguserid property is set during plug-in registration, this line of code effectively ignores that setting for any Web method calls to the Web service.

For plug-ins executing offline, any entities created by the plug-in are owned by the logged on user. Impersonation in plug-ins is not supported while in offline mode.

Note   When you register a plug-in by using the plug-in registration sample tools that are provided with the SDK, Web service methods invoked by the plug-in always execute under the account of the calling or logged on user. The tools do not offer impersonation as a supported feature. For more information about the tool sample code, see Sample Code.