- Overview
- Approaches to single account aggregation
- The user interface / LCM approach
- The application configuration approach
- The API based approach
- Execution of the API approach
- Reference artifacts
- Forum discussions related to this topic
Overview
Deployment professionals configuring IdentityIQ sometimes a need to update IdentityIQ's model of a single account from an Application without the overhead and time needed for a full re-aggregation of all accounts from the Application. This concept is called "single account aggregation", "targeted aggregation", or "single-account targeted aggregation". These terms can be use interchangeably. This article discusses approaches and examples that can be used to achieve single account aggregation in IdentityIQ.
By default, IdentityIQ aggregations process every account from the Application(s) being aggregated. This behavior is designed to support the Access Review and Certification features of IdentityIQ where a complete, current, and accurate data set is required for a Certification to be valid. When using IdentityIQ for provisioning and access-request and request-approval functions, a more real-time approach to retrieving the status of an account is necessary.
Most connector technologies in IdentityIQ support the concept of "Single account" aggregation. An notable exception to this is the delimited file connector, which due to the nature of how it reads data from a large delimited file, is unable to retrieve a single individual account. In addition, the JDBC connector requires the "getObjectSQL" parameter to be configured to support retrieving Account information one account at a time. For most other connectors, the capability to retrieve an account in a one-off fashion is built into the connector technology. At the code layer of the connector technology, the connector class must support the "getObject()" method in order to support single-account aggregation.
Approaches to single account aggregation
There are three ways in IdentityIQ to update the model of a single account, without running a full account aggregation against an application:
1) Via the user interface for LCM under Manage Access -> Manage Accounts -> For Others, select the Identity correlated to the account.
2) Modify the Application configuration temporarily with a filter include only the desired accounts, then run an aggregation.
3) Programmatically via the API, invoke the Aggregator to aggregate the single account directly.
The user interface / LCM approach
The first option uses the LCM features of IdentityIQ to refresh the status of an Identity's accounts. Under Manage Access -> Manage Accounts -> For Others, select the Identity correlated to the account you want to re-aggregate. Most directly-connected Applications will automatically re-aggregate the account in real time to update the status of the account when this page is loaded. For other connector technologies a "refresh" button is provided on the right side of the screen which will cause IdentityIQ to re-aggregate that single specific account. An example of this part of the user interface is shown here:
The application configuration approach
The second option, discussed here (https://community.sailpoint.com/message/10188#10188) is cumbersome in that it requires administrative access to change the Application's configuration and then the execution of a specifically configured Account Aggregation task to operate. In some scenarios it can work but in general it is not a recommended solution for everyday use.
The API based approach
The third option, the API-based option, is used to automate a number of processes on installations that need close to real-time accuracy of account information in IdentityIQ. This is the recommended approach for installations that need to electronically automate the process of having IdentityIQ update a single account's status from an Application. This approach has the advantage of allowing the user to pass information about an account that IdentityIQ has never seen before, allowing a single new account to be added to IdentityIQ's model without requiring a full re-aggregation. This approach also allows IdentityIQ to detect account deletions if the account name passed to the single account aggregation has been removed from the Application.
The following example snippet shows how to use the API-based approach, and a code review is provided below.
import sailpoint.object.Application;
import sailpoint.object.Attributes;
import sailpoint.object.Custom;
import sailpoint.object.Filter;
import sailpoint.object.Identity;
import sailpoint.object.Link;
import sailpoint.object.QueryOptions;
import sailpoint.object.ResourceObject;
import sailpoint.object.TaskResult;
import sailpoint.object.Rule;
import sailpoint.connector.JDBCConnector;
import sailpoint.api.Aggregator;
import sailpoint.connector.Connector;
import org.apache.log4j.Logger;
import org.apache.log4j.Level;
// Declare a logger class for us to isolate these messages during aggregation.
// Force the log level to DEBUG for initial testing.
Logger log = Logger.getLogger("sailpoint.services.DemonstrateSingleAccountAggregation");
log.setLevel(Level.DEBUG); // TODO: Turn this off or remove this line when checking in.
// Initialize the error message to nothing.
String errorMessage = "";
// We need some values defined to know which account we want to aggregate.
String applicationName = "SampleDB";
String accountName = "clyde.orangous";
// We have already validated all of the arguments. No just load the objects.
Application appObject = context.getObjectByName(Application.class, applicationName);
String appConnName = appObject.getConnector();
log.debug("Application " + applicationName + " uses connector " + appConnName);
Connector appConnector = sailpoint.connector.ConnectorFactory.getConnector(appObject, null);
if (null == appConnector) {
errorMessage = "Failed to construct an instance of connector [" + appConnName + "]";
return errorMessage;
}
log.debug("Connector instantiated, calling getObject() to read account details...");
ResourceObject rObj = null;
try {
rObj = (ResourceObject) appConnector.getObject("account", accountName, null);
} catch (sailpoint.connector.ObjectNotFoundException onfe) {
errorMessage = "Connector could not find account: [" + accountName + "]";
errorMessage += " in application [" + applicationName + "]";
log.error(errorMessage);
log.error(onfe);
return errorMessage;
}
if (null == rObj) {
errorMessage = "ERROR: Could not get ResourceObject for account: " + accountName;
log.eror(errorMessage);
return errorMessage;
}
log.debug("Got raw resourceObject: " + rObj.toXml());
// Now we have a raw ResourceObject. The Application in IdentityIQ may have a
// Customization rule defined to transform the ResourceObject. We need to
// honor that configuration, so if the Applicaiton has a Rule then we run it.
Rule customizationRule = appObject.getCustomizationRule();
if (null != customizationRule) {
log.debug("Customization rule found for applicaiton " + applicationName);
try {
// Pass the mandatory arguments to the Customization rule for the app.
HashMap ruleArgs = new HashMap();
ruleArgs.put("context", context);
ruleArgs.put("log", log);
ruleArgs.put("object", rObj);
ruleArgs.put("application", appObject);
ruleArgs.put("connector", appConnector);
ruleArgs.put("state", new HashMap());
// Call the customization rule just like a normal aggregation would.
ResourceObject newRObj = context.runRule(customizationRule, ruleArgs, null);
// Make sure we got a valid resourceObject back from the rule.
if (null != newRObj) {
rObj = newRObj;
log.debug("Got post-customization resourceObject: " + rObj.toXml());
}
} catch (Exception ex) {
// Swallow any customization rule errors, the show must go on!
log.error("Error while running Customization rule for " + applicationName);
}
}
// Next we perform a miniature "Aggregation" using IIQ's built in Aggregator.
// Create an arguments map for the aggregation task.
// To change this (if you need to), the map contains aggregation options and is the same as the
// arguments to the acocunt aggregation tasks. Some suggestied defaults are:
Attributes argMap = new Attributes();
argMap.put("promoteAttributes", "true");
argMap.put("correlateEntitlements", "true");
argMap.put("noOptimizeReaggregation", "true"); // Note: Set to false to disable re-correlation.
// Consturct an aggregator instance.
Aggregator agg = new Aggregator(context, argMap);
if (null == agg) {
errorMessage = "Null Aggregator returned from constructor. Unable to Aggregate!";
log.eror(errorMessage);
return errorMessage;
}
// Invoke the aggregation task by calling the aggregate() method.
// Note: the aggregate() call may take serveral seconds to complete.
log.debug("Calling aggregate() method... ");
TaskResult taskResult = agg.aggregate(appObject, rObj);
log.debug("aggregation complete.");
if (null == taskResult) {
errorMessage = "ERROR: Null taskResult returned from aggregate() call.";
log.eror(errorMessage);
return errorMessage;
}
// Show the task result details for engineers curious about the results.
// These ususally look like the following:
// <?xml version='1.0' encoding='UTF-8'?>
// <!DOCTYPE TaskResult PUBLIC "sailpoint.dtd" "sailpoint.dtd">
// <TaskResult>
// <Attributes>
// <Map>
// <entry key="applications" value="1"/>
// <entry key="exceptionChanges" value="1"/>
// <entry key="extendedAttributesRefreshed" value="1"/>
// <entry key="identityEntitlementsCreated" value="1"/>
// <entry key="identityEntitlementsIndirectLinkUpdates" value="1"/>
// <entry key="identityEntitlementsRoleAssignmentsUpdates" value="4"/>
// <entry key="identityEntitlementsRoleDetectionsUpdates" value="1"/>
// <entry key="identityEntitlementsUpdated" value="1"/>
// <entry key="total" value="1"/>
// <entry key="updated" value="1"/>
// </Map>
// </Attributes>
// </TaskResult>
// Where the "udpated" indiciates the number of account links updated.
log.debug("TaskResult details: \n" + taskResult.toXml());
return ("Success");
Lines 1 through 20 define the includes and logging.
Line 21 should be removed when using this code in production; it sets logging levels for demonstration purposes.
Lines 26 through 28 specify the Application Name and Account Name for the account to aggregate.
Lines 30 through 41 instantiate the Application and its Connector in local memory.
Lines 43 through 62 read back the "ResourceObject" from the Connector. The ResourceObject represents the account before it has been correlated and "Link"-ed to an Identity object.
Lines 64 through 99 execute the Application's Customization Rule on the ResourceObject returned from the Connector. This allows single-account aggregations to have the same customizations applied as full aggregations run from Aggregation tasks.
Lines 101 through 128 construct an instance of the Aggregator class to aggregate the single account. They return a TaskResult reference with statistics about the aggregation.
Lines 130 through 152 log the details of the Aggregation's TaskResult to the log file.
Execution of the API approach
When imported and executed from "iiq console" the code above provides the following output:
> import "/Users/adam.hampton/Documents/workspace/ssb-keppler-baremetal/config/Rule/Rule-Demonstrate-Single-Account-Aggregation.xml
Rule:Demomstrate Single Account Aggregation
> rule "Demomstrate Single Account Aggregation"
2015-12-09 10:39:37,845 DEBUG main sailpoint.services.DemonstrateSingleAccountAggregation:? - Application SampleDB uses connector sailpoint.connector.JDBCConnector
2015-12-09 10:39:37,857 DEBUG main sailpoint.services.DemonstrateSingleAccountAggregation:? - Connector instantiated, calling getObject() to read account details...
2015-12-09 10:39:37,858 DEBUG main sailpoint.connector.JDBCConnector:1048 - SQL statement[select * from users where login = 'clyde.orangous'].
2015-12-09 10:39:37,858 DEBUG main sailpoint.connector.JDBCConnector:1412 - Returned from execute [true].
2015-12-09 10:39:37,860 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [login]
2015-12-09 10:39:37,860 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [description]
2015-12-09 10:39:37,860 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [first]
2015-12-09 10:39:37,860 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [last]
2015-12-09 10:39:37,860 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [role]
2015-12-09 10:39:37,860 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [status]
2015-12-09 10:39:37,860 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [locked]
2015-12-09 10:39:37,861 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [email]
2015-12-09 10:39:37,861 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [roleFlag]
2015-12-09 10:39:37,861 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [password]
2015-12-09 10:39:37,861 DEBUG main sailpoint.connector.JDBCConnector:1627 - Building attribute [postalcode]
2015-12-09 10:39:37,861 DEBUG main sailpoint.connector.JDBCConnector:516 - SQL statement for Direct Permission is null
2015-12-09 10:39:37,863 DEBUG main sailpoint.services.bshdemo.customizationRule:? - account [clyde.orangous] has status [A], setting disabled false.
2015-12-09 10:39:37,864 DEBUG main sailpoint.services.bshdemo.customizationRule:? - account [clyde.orangous] has locked [N], setting locked false.
2015-12-09 10:39:37,864 DEBUG main sailpoint.services.bshdemo.customizationRule:? - Performing one-time load of 'postalCodeLookupMap'...
2015-12-09 10:39:37,865 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:10007 to state:NY
2015-12-09 10:39:37,866 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:77077 to state:TX
2015-12-09 10:39:37,866 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:78747 to state:TX
2015-12-09 10:39:37,866 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:78748 to state:TX
2015-12-09 10:39:37,866 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:78749 to state:TX
2015-12-09 10:39:37,869 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:81003 to state:CO
2015-12-09 10:39:37,869 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:90405 to state:CA
2015-12-09 10:39:37,870 DEBUG main sailpoint.services.bshdemo.customizationRule:? - No 'postalcode' field/property found on account:clyde.orangous
2015-12-09 10:39:37,871 DEBUG main sailpoint.services.DemonstrateSingleAccountAggregation:? - Got raw resourceObject: <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE ResourceObject PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<ResourceObject displayName="clyde.orangous" identity="clyde.orangous" objectType="account">
<Attributes>
<Map>
<entry key="IIQDisabled">
<value>
<Boolean></Boolean>
</value>
</entry>
<entry key="IIQLocked">
<value>
<Boolean></Boolean>
</value>
</entry>
<entry key="email" value="clyde.orangous@acme.com"/>
<entry key="first" value="ornage"/>
<entry key="last" value="Clyde-primus"/>
<entry key="locked" value="N"/>
<entry key="login" value="clyde.orangous"/>
<entry key="role">
<value>
<List>
<String>User</String>
</List>
</value>
</entry>
<entry key="status" value="A"/>
</Map>
</Attributes>
</ResourceObject>
2015-12-09 10:39:37,871 DEBUG main sailpoint.services.DemonstrateSingleAccountAggregation:? - Customization rule found for applicaiton SampleDB
2015-12-09 10:39:37,873 DEBUG main sailpoint.services.bshdemo.customizationRule:? - account [clyde.orangous] has status [A], setting disabled false.
2015-12-09 10:39:37,874 DEBUG main sailpoint.services.bshdemo.customizationRule:? - account [clyde.orangous] has locked [N], setting locked false.
2015-12-09 10:39:37,874 DEBUG main sailpoint.services.bshdemo.customizationRule:? - Performing one-time load of 'postalCodeLookupMap'...
2015-12-09 10:39:37,875 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:10007 to state:NY
2015-12-09 10:39:37,875 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:77077 to state:TX
2015-12-09 10:39:37,875 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:78747 to state:TX
2015-12-09 10:39:37,876 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:78748 to state:TX
2015-12-09 10:39:37,876 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:78749 to state:TX
2015-12-09 10:39:37,876 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:81003 to state:CO
2015-12-09 10:39:37,876 DEBUG main sailpoint.services.bshdemo.customizationRule:? - loaded mapping of zipcode:90405 to state:CA
2015-12-09 10:39:37,877 DEBUG main sailpoint.services.bshdemo.customizationRule:? - No 'postalcode' field/property found on account:clyde.orangous
2015-12-09 10:39:37,878 DEBUG main sailpoint.services.DemonstrateSingleAccountAggregation:? - Got post-customization resourceObject: <?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE ResourceObject PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<ResourceObject displayName="clyde.orangous" identity="clyde.orangous" objectType="account">
<Attributes>
<Map>
<entry key="IIQDisabled">
<value>
<Boolean></Boolean>
</value>
</entry>
<entry key="IIQLocked">
<value>
<Boolean></Boolean>
</value>
</entry>
<entry key="email" value="clyde.orangous@acme.com"/>
<entry key="first" value="ornage"/>
<entry key="last" value="Clyde-primus"/>
<entry key="locked" value="N"/>
<entry key="login" value="clyde.orangous"/>
<entry key="role">
<value>
<List>
<String>User</String>
</List>
</value>
</entry>
<entry key="status" value="A"/>
</Map>
</Attributes>
</ResourceObject>
2015-12-09 10:39:37,878 DEBUG main sailpoint.services.DemonstrateSingleAccountAggregation:? - Calling aggregate() method...
2015-12-09 10:39:39,010 DEBUG main sailpoint.services.DemonstrateSingleAccountAggregation:? - aggregation complete.
2015-12-09 10:39:39,011 DEBUG main sailpoint.services.DemonstrateSingleAccountAggregation:? - TaskResult details:
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE TaskResult PUBLIC "sailpoint.dtd" "sailpoint.dtd">
<TaskResult>
<Attributes>
<Map>
<entry key="applications" value="SampleDB"/>
<entry key="identityEntitlementsIndirectLinkUpdates" value="1"/>
<entry key="identityEntitlementsIndirectUpdates" value="1"/>
<entry key="identityEntitlementsRoleAssignmentsUpdates" value="1"/>
<entry key="identityEntitlementsRoleDetectionsUpdates" value="1"/>
<entry key="identityEntitlementsUpdated" value="1"/>
<entry key="internalUpdates" value="1"/>
<entry key="total" value="1"/>
<entry key="updated" value="1"/>
</Map>
</Attributes>
</TaskResult>
Success
Reference artifacts
Two examples are attached to this document: A Workflow, and a Rule that implements the API-based approach for reference. These can be used as copy/paste ready examples for use in your projects.
Forum discussions related to this topic
The following list includes older forum discussions related to this topic that may have partially correct or outdated information related to this topic.
- https://community.sailpoint.com/message/11408#11408
- https://community.sailpoint.com/message/10300#10300
- https://community.sailpoint.com/message/12344#12344
- https://community.sailpoint.com/message/11378#11378
- https://community.sailpoint.com/message/30750#30750
- https://community.sailpoint.com/message/14535#14535
- https://community.sailpoint.com/message/10188#10188
