Before and After Scripts for IQService

The IQService supports function customization by allowing integrating Before/After scripts implemented in languages like PowerShell and Batch. Scripts can be used to automate any required actions that cannot be automated using current source functions. Scripts called before processing the request are referred to as Native Before Scripts and scripts called after processing the request are referred to as Native After Scripts.

Identity Security Cloud provides most of the provisioning functionality for many systems through its connectors. Some systems provide a better integration interface from the Windows platform compared to other platforms. So connectors for these systems require IQService deployed on a Windows system. The IQService implementation performs the provisioning functions (such as Add User, Connect User to a Group) that are supported by the respective managed system. The IQService functions are called by the Identity Security Cloud source implementation.

In addition to the basic action, some organizations may require supplementary actions performed by each function from the Windows system. The IQService supports customization of the functions by allowing you to integrate Before and After scripts in any language. The following are some features of IQService Before and After scripts:

  • Centralized configurations (in Identity Security Cloud) for setting up Before and After scripts

  • Supports Object Oriented scripting

  • Script refers SailPoint library to get the request and result classes

  • Can be executed with specific context

  • Script can modify requests and results

A script is a group of statements that perform one or more actions and manipulate request and result attributes. Scripts can be used to automate any required actions.

The scripts need to be defined in a rule and then configured for a source in Identity Security Cloud. Based on the rule type (Before or After), the connector sends the scripts to be executed before or after processing the request to IQService.

IQService supports executing Before and After Rules for Create, Modify, and Delete request operations.

Writing a Script

IQService divides scripts in the following categories:

  • Scripts with Object Oriented support

  • Scripts without Object Oriented support

Scripts with Object Oriented Support

Scripting languages with Object Oriented capabilities (for example, PowerShell) are popular because of their simplistic nature and ease of use. These scripts can form objects of any type by referring to any library or assembly implemented in any language and call its methods.

Native scripts implemented in these languages have easier and more powerful access to request and result objects. IQService comes with a class library named Utils.dll which bundles all required classes to access the request and result objects. The inputs provided to the script are in the form of process environment variables. The following table describes the environment variables created by IQService:

Name

Type

Before Script

After Script

Application

System.Collections.Hashtable

Read Only

Read Only

Request

SailPoint.Utils.objects.AccountRequest

Read/Write

Read Only

Result

SailPoint.Utils.objects.ServiceResult

Not Available

Read/Write

The data in the environment variables is in XML. The script creates respective objects using Utils.dll. Once the object is modified, the script converts it to XML by calling the toxml() method of the object and then writes a file at the path passed as the only argument to the script to the XML.

The script returns a non-zero value if an error occurs. It writes the error message in the file at the path passed as the argument to the script. This failure is communicated to Identity Security Cloud as part of a result.

The following is a sample PowerShell Before script which modifies the value of an attribute and adds one new attribute to the request:

Copy 
# Refer to SailPoint class library Requires PowerShell v2 installed on the system.
Add-type -path utils.dll
# Read the environment variables
$sReader = New-Object System.IO.StringReader([System.String]$env:Request);

# Form the xml reader object
$xmlReader = [System.xml.XmlTextReader]([SailPoint.Utils.xml.XmlUtil]::getReader($sReader));

# Create SailPoint Request object
$requestObject = New-Object SailPoint.Utils.objects.AccountRequest($xmlReader);

# Loop through the attributes from the request for each ($attribute in $requestObject.AttributeRequests){
if($attribute.Name -eq "description"){
$attribute.value = "my description"; #change value of the attribute
}
}

# Add a new attribute to request
$attributeObject = New-Object SailPoint.Utils.objects.AttributeRequest;
$attributeObject.Name = "otherMobile";
$otherMobileValues = New-Object System.Collections.ArrayList;
$otherMobileValues.Add("222-292-2929");
$otherMobileValues.Add("333-292-2929");
$attributeObject.Value= $otherMobileValues;
$attributeObject.Operation = "Set";
$requestObject.AttributeRequests.Add($attributeObject);

# Write the request xml to file at the path passed as argument
$requestObject.toxml()|out-file $args[0];

  • The following is a sample PowerShell After script which ensures that the request was processed successfully and creates a home directory at the path specified in the request:

    Copy 
    # Refer to SailPoint class library. Requires PowerShell v2 installed on the system.
    Add-type -path E:\SVN\trunk\src\WinRPCGateway\IQService\bin\Debug\utils.dll

    # Read the environment variables
    $sReader = New-Object System.IO.StringReader([System.String]$env:Request);
    $sResult = New-Object System.IO.StringReader([System.String]$env:Result);

    # Form the xml reader objects
    $xmlReader = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sReader));
    $xmlReader_Result = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sResult));

    # Create SailPoint objects
    $requestObject = New-Object Sailpoint.Utils.objects.AccountRequest($xmlReader);
    $resultObject = New-Object Sailpoint.Utils.objects.ServiceResult($xmlReader_Result);

    #Check if the request was processed successfully
    if($resultObject.Errors.count -eq 0){

    #Get Home directory path
    foreach ($attribute in $requestObject.AttributeRequests){

    #Create Home directory
    if($attribute.Name -eq "TS_TerminalServicesHomeDirectory"){
    new-item $attribute.Value -itemtype directory;
    }
    }
    }

  • The following script displays how to access any application configuration attribute in the script. The following example reads application attributes with the name, Office365Username and its associated password. It uses them to connect to Exchange Online and sets Mailbox properties:

    Copy 
    # Refer to SailPoint class library.
    Add-type -path C:\Program files\IQService\bin\Debug\utils.dll

    # Read the environment variables
    $sReader = New-Object System.IO.StringReader([System.String]$env:Request);
    $sResult = New-Object System.IO.StringReader([System.String]$env:Result);

    # Form the xml reader objects
    $xmlReader = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sReader));
    $xmlReader_Result = [ System.xml.XmlTextReader]([sailpoint.utils.xml.XmlUtil]::getReader($sResult));

    # Create SailPoint objects
    $requestObject = New-Object Sailpoint.Utils.objects.AccountRequest($xmlReader);
    $resultObject = New-Object Sailpoint.Utils.objects.ServiceResult($xmlReader_Result);

    # Retrieve nativeIdentity from request object
    $nativeIdentity = $requestObject.NativeIdentity

    # Get xmlFactory object to retrieve application configuration
    $xmlFactory = [sailpoint.Utils.xml.XmlFactory]::Instance;

    # Read the environment variables
    $sReader1 = $env:Application

    # Retrieve application configuration object
    $appObject = $xmlFactory.parseXml($sReader1)

    #Retrieve application configuration entries named Office365username and password value from AzureAD application config
    $office365AdminUsername = $appObject.Office365username

    #Retrieve password attribute value
    $o365Password = $appObject.password

    #create Credential object
    $secpasswd = ConvertTo-SecureString $o365Password -AsPlainText -Force
    $cred = New-Object System.Management.Automation.PSCredential ($office365AdminUsername, $secpasswd)

    #Connect to Office365
    Import-Module msonline
    Connect-MsolService -Credential $cred

    #Connect Exchange-Online
    $msoExchangeURL = "https://ps.outlook.com/powershell/"
    $session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri $msoExchangeURL -Credential $cred -Authentication Basic -AllowRedirection
    Import-PSSession $session

    # Set mailbox properties
    Set-MailBox -identity $nativeIdentity -UseDatabaseQuotaDefaults $false -IssueWarningQuota "200MB" -ProhibitSendQuota "250MB" -ProhibitSendReceiveQuota "280MB"

Scripts without Object Oriented Support

Non-Object Oriented scripts do not refer to the class library or support a way of parsing XML. To have easy access to each attribute along with their operation and values, IQService creates process environment variables for each of the application and request attributes. It formats the names as SP_<OPERATION>_<NAME> for requests and SP_APP_<NAME> for applications. For native identity, the environment variable is SP_NativeIdentity. These types of scripts have limited access to results and get only SUCCESS or FAIL in the Result environment variable. So the After scripts implemented using these scripting languages cannot modify any attribute or result. Before scripts can add, modify, or remove any attribute from the request. The script needs to write the newly added or modified attribute to the file at the path passed as an argument to the script in the form SP_<OPERATION>_<NAME>=<VALUE>. To remove the attribute from the request, write /~<ATTRIBUTE_NAME> to the file. The value for the multivalued attribute is delimited by /#/.

The following is a sample batch After script which ensures that the request was processed successfully and creates a home directory at the path specified in the request:

IF %Result% ==SUCCESS md %SP_Set_TS_TerminalServicesHomeDirectory%

Creating a Rule

To add the script to a rule and use it, you need to create a rule. Contact SailPoint Services for assistance on creating rule as per requirement.

Configuring the Rules in Source

Add the nativeRules attribute under the Attributes map with a list of rules that must be configured for a source in Identity Security Cloud using the REST API.

Note
For more information on SailPoint's REST APIs, refer to Best Practices: REST API Authentication and REST API - Update Source (Partial) in the SailPoint Developer Community.