D.3 Implementing PowerShell Cmdlets in the Active Directory Driver

To call cmdlets, create a rule which adds the PSExecute containing the PowerShell command string.

The Active Directory driver looks for the PSExecute attribute in the input XDS code, reads any cmdlets embedded in a <value/> tag, and sends those commands to the Exchange service running on the Active Directory server. The Active Directory server executes the commands sequentially using a programmatic PowerShell interface.

NOTE:When including the PSExecute attribute in an Add or Modify event policy, you must adhere to the XDS format, or the driver ignores the embedded cmdlets.

D.3.1 Sample Active Directory Policy Rule with Cmdlets

The following is a sample rule created in an Active Directory driver policy that allows an administrator to disable a newly-created user account in Active Directory using the Disable-ADAccount cmdlet.

<rule>
  <description>Adding PSExecute to Disable New User Account</description>
  <conditions>
   <and>
    <if-operation mode="regex" op="not-equal">query|status</if-operation>
   </and>
  </conditions>
  <actions>
   <do-set-local-variable name="identityname" scope="policy">
    <arg-string>
     <token-xpath expression='./add-attr[@attr-name="sAMAccountName"]/value/text()'/>
    </arg-string>
   </do-set-local-variable>
   <do-set-dest-attr-value name="PSExecute">
    <arg-value type="string">
     <token-text xml:space="preserve">Disable-ADAccount -Identity </token-text>
     <token-local-variable name="identityname"/>
    </arg-value>
   </do-set-dest-attr-value>
  </actions>
 </rule>

Note that the example rule above is used for including a PowerShell cmdlet in an Add event. You can also create rules to include PowerShell cmdlets in other types of events. However, if you include a cmdlet in a Modify event, ensure that you use the XDS format for constructing that type of event and including the PSExecute attribute.

Specifically, the PSExecute attribute must include XDS code similar to the following example, where the <value> tag includes the PowerShell command string:

   <modify-attr attr-name="PSExecute">
    <add-value>
     <value type="string">New-ADUser -SamAccountName rbigby
-Name "Robin Bigby" -AccountPassword (ConvertTo-SecureString -AsPlainText
"NetIQ1234" -Force) -Enabled $true -Path
'ou=active,ou=workforce,dc=w2008r2vm,dc=com'</value>
    </add-value>
   </modify-attr>

D.3.2 Available Active Directory and Exchange Cmdlets

PowerShell includes a wide variety of cmdlets and functions. However, the Active Directory driver only supports Active Directory and Exchange PowerShell modules and cmdlets. For information about using Active Directory PowerShell cmdlets, see “Active Directory Cmdlets in Windows PowerShell”. For information about using Exchange cmdlets, see “Cmdlets”.

NOTE:You can use the PSExecute attribute only with Active Directory and Exchange Cmdlets. It cannot be used for scripting.

D.3.3 Creating Active Directory Policies with Cmdlets

To use cmdlets in Identity Manager, first use Designer to create a new policy in the Active Directory driver. For more information about creating policies in Designer, see Policies in Designer and Understanding Policies for Identity Manager.

After you create a new policy, add a rule to the policy that includes an add destination attribute value action to create the PSExecute attribute, which calls one or more PowerShell cmdlets. You can include several cmdlet strings in multiple value tags for a single PSExecute attribute, as necessary.

To configure the rule using the Policy Builder, complete the following steps:

  1. In Designer, right-click the policy in the Outline view and select Edit.

  2. In the Policy Builder, select the location where you want to create the PSExecute attribute.

  3. In the toolbar, click Rule and select Action > Insert Action After.

  4. In the Do field under Define new action below, select add destination attribute value.

  5. Specify PSExecute as the attribute name.

  6. In the Select mode field, select add to current operation.

  7. In the Select object field, select Current object.

  8. In the Specify value type field, select string.

  9. In the Enter string field, specify the PowerShell command string you want to use, enclosed in quotation marks.

  10. Click OK.

  11. Save the policy.

When specifying the PowerShell command string, you can include other variables configured in separate actions within the rule, as necessary.

For example, for the sample policy provided in Section D.3.1, Sample Active Directory Policy Rule with Cmdlets, you first add a rule to define the variable identityname as the name of the user account you want to disable using a PowerShell cmdlet, and then you specify the following string for the PSExecute variable, which uses the new identityname variable in the PowerShell command string:

"Disable-ADAccount -Identity"+Local Variable("identityname")

NOTE:You can also configure a policy to execute a specified cmdlet by modifying the XML directly, in the XML Source tab of the Policy Builder.

D.3.4 Verifying Active Directory Cmdlet Execution

When a PowerShell cmdlet runs successfully, the Active Directory returns a specific success event in the output XML, with the type powershell. After you run a cmdlet, check the output XML file for the following event:

<status level="success" event-id="linux-djs#20120510164317#1#2:facdcbbb-d440-4340-1b85-bbcbcdfa40d4" type="powershell"/>

If the PowerShell cmdlet does not run successfully, the driver instead logs an error event in the output XML. The error event is similar to the following, including the reason for the failure:

<status level="error" type="powershell" text1="Exchange 2007" event-id="linux-djs#20120528111905#99#1:a6ff6b29-950a-4141-8093-296bffa60a95">Exchange 2007 Exception. code:0x000000b8 Error completing exchange 2007 command.  ERROR: Cannot process command because of one or more missing mandatory parameters: Identity.</status>

NOTE:If you execute multiple cmdlets in a single rule and one of the cmdlets does not run successfully, the driver does not execute any subsequent cmdlets in the rule and only logs the error event for the failed cmdlet. The driver does not log error events for the subsequent cmdlets, even though they did not run successfully, because the driver does not run those cmdlets after the failure occurs.