API changes - Changes to implementing a provisioning integration

[#1]

Affected Audience: IdentityIQ 5.1 or greater upgraders and implementers

Summary: Architectural changes to the standard way provisioning integrations should be approached using the 5.1 platform or greater.

The basic structure of a sailpoint.object.ProvisioningPlan in XML is:

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE ProvisioningPlan PUBLIC "sailpoint.dtd" "sailpoint.dtd">

<ProvisioningPlan>

  <AccountRequest application='HR' op='Modify' nativeIdentity='jeff'>

    <AttributeRequest name='groups' op='Add' value='Illuminati'/>

  </AccountRequest>

</ProvisioningPlan>

If you include the <?xml... and <!DOCTYPE lines you will get XML validation which is helpful. Though you can specify the target IdentityIQ identity in the plan, from the IdentityIQ console you have to specify this as a command line argument so it is not in the plan. From this, you then make an AccountRequest element for each application account you want to target, changing the application and nativeIdentity attribute values as appropriate. The nativeIdentity must match the "identity" attribute of the link, for directories. In other words, it must be the full DN and not the display name. The "op" attribute in AccountRequest defaults to Modify, so it can be omitted most of the time. The "op" attribute in the AttributeRequest defaults to Add, so this is also often omitted. To test creation of a new account, change the AccountRequest op to Delete and add the other attributes the resource requires.

<ProvisioningPlan>

  <AccountRequest application='HR' op='Create' nativeIdentity='jeff'>

    <AttributeRequest name='password' value='xyzzy'/>

    <AttributeRequest name='groups' value='Illuminati'/>

  </AccountRequest>

</ProvisioningPlan>

To delete an account change AccountRequest op to Delete. You do not usually have AttributeRequests when deleting accounts but some connectors allow them to pass options such as whether to cascade delete other things associated with the account.

<ProvisioningPlan>

  <AccountRequest application='HR' op='Delete' nativeIdentity='jeff'/>

</ProvisioningPlan>

Disable, enable, and unlock are also AccountRequest ops and may or may not be accompanied by AttributeRequests.

  <AccountRequest application='HR' op='Disable' nativeIdentity='jeff'/>

  <AccountRequest application='HR' op='Enable' nativeIdentity='jeff'/>

  <AccountRequest application='HR' op='Unlock' nativeIdentity='jeff'/>

The three operations available for AttributeRequest are Set, Add, and Remove. Add is the default operation. Set and Add behave the same if the attribute is single valued. If the attribute is multi-valued, Set replaces the values and Add and Remove make incremental changes.

Add a group:

<AttributeRequest name='groups' op='Add' value='Malcontents'/>

Remove a group:

<AttributeRequest name='groups' op='Remove' value='Malcontents'/>

Replace the group list:

<AttributeRequest name='groups' op='Set'>

  <value>

    <List>

      <String>Hunters</String>

      <String>Gatherers</String>

    </List>

  </value>

</AttributeRequest>

That last example shows how to specify complex values. Almost always you are dealing with string values so you can just use the "value" XML attribute. But if you need to use a List, Date, or other object, you have to use the more verbose <value> element. <value> can contain anything that is in the SailPoint DTD but for connectors is should be limited to <String>, <Integer>, <Boolean>, <List>, and <Date>.

Most connectors do coercion and for those that don't, the Provisioner will, so if you need to set an integer attribute you can do this:

<AttributeRequest name='mailboxSize op='Set'>

   <value>

     <Integer>100</Integer>

   </value>

</AttributeRequest>

or you can just do this:

<AttributeRequest name='mailboxSize' op='Set' value='100'/>

or since Set and Add are the same for single valued attributes and Add is the default operation, it can simplify to this:

<AttributeRequest name='mailboxSize' value='100'/>

If you want to target the IdentityIQ identity rather than an application account you create an AccountRequest with the application name "IIQ".

<ProvisioningPlan>

   <AccountRequest application='IIQ' nativeIdentity='jeff'>

     <AttributeRequest name='assignedRoles' value='Candy Men'/>

   </AccountRequest>

</ProvisioningPlan>

To manipulate the permission list you create <PermissionRequest> elements which are much like AttributeRequests:

<ProvisioningPlan>

   <AccountRequest application='Some Database' nativeIdentity='jeff'>

     <PermissionRequest target='HR Employees' op='Add' rights='read,write,delete'/>

   </AccountRequest>

</ProvisioningPlan>

Since rights are always strings they are specified as a CSV. Since permission rights are always multi-valued the Set and Add operations will behave differently. You can have any combination of AccountRequest, AttributeRequest, and PermissionRequests in a plan. If you want to construct a ProvisioningPlan object in Java and then save the XML to a file you can do this:

ProvisioningPlan plan = ...build a plan...

System.out.println(plan.toXml());

sailpoint.tools.Util.writeFile("plan.xml", plan.toXml());