Aggregating a single account from an application

46 Kudos

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">

<Map>

<value>

</value>

</entry>

<value>

</value>

</entry>

<value>

<List>

</List>

</value>

</entry>

</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">

<Map>

<value>

</value>

</entry>

<value>

</value>

</entry>

<value>

<List>

</List>

</value>

</entry>

</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">

<Map>

</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.

nukem23 · ‎Aug 17, 2018

Thanks, very usefull trick. It solved my issue.

amit_jaiswal · ‎Dec 18, 2018

Hi James,

Were you able to achieve it? I mean when you say duplicate link,does that mean you see two AD account for one identity?

let me know if you can help.

we are facing issue that AD account is getting removed automatically when we run Leaver/REhire but they comes back once AD AA tasks runs.

amit_jaiswal · ‎Dec 18, 2018

Hi Gaurav/Sridhar,

were you able achieve it via setting optimisticProvisioning as true?

we have faced issue while running LEaver/Rehire (with OU movement) for identities where AD account was removed automatically after running these LCE and comes back after running AD aggregation task.

matoch · ‎Dec 18, 2018

Amit,

I wouldn't say it's been resolved yet. We moved on from the issue for awhile as were not deployed into production yet. A recent discussion with SailPoint has suggested that we enable locking on the single account aggregation and handle it later on in the workflow. We figure that disabling locking during the aggregation and having it run in the after provisioning rule is the cause of our issue.

James

amit_jaiswal · ‎Dec 20, 2018

Hi Kroeten,

We are facing issue that after running LCE(leaver/Rehire including OU movement), AD link is getting disappeared but after AD AA task it appears back.

do you think your solution will help on it. and does refreshLink=true refresh links for that particular identity or all identity (kind of refresh identity cube task).

because we dont want to run for all.

gaurav_jain · ‎Dec 21, 2018

Amit,

I used this with optimistic provisioning also and never came across such issue. Probably checking your provisioning plan after modification might help debugging the issue.

Thanks,

Gaurav

vkondam · ‎Feb 25, 2019

I'm calling Single Account Aggregation method in After Provisioning Rule of AD application. For some reason for a newly on-boarded user, In Identity I was noticing account links were duplicated i.e., the old AD link is NOT been updated with new DN.

I tried by adding argMap.put("checkDeleted", "true"); to perform detect delete account. (to delete orphan link). But It's not working for me.

Could any suggest your thoughts.

serge_voina · ‎Mar 04, 2019

Hi vkondam,

This happens because the request is not finished yet. A workaround would be to schedule another workflow (with has single account aggregation) from ‘After Provisioning Rule’. In such case the identity cube will be updated before you run the single account aggregation.

mike818148 · ‎Jan 20, 2020

Hello @adam_hampton,

First of all thanks a lot for such good article.

Just a recommendation, the Customization Rule can not be retrieved if the objectType not specified.

Rule customizationRule = appObject.getCustomizationRule("account");

P.s. I am testing this on IIQ8.0p1

- Mike

T_C · ‎Feb 27, 2020

When aggregating a single account using the Active Directory connector, various required attributes are not found (even though they are located under the domainSettings entry. @sean_flynn noted “I was able to get around this by duplicating the entries from within the application xml. Basically I added the authorizationType, host, port, and user and password into the root of the xml not in the DomainSettings sections. Basically I have duplicate entries in the xml and that seemed to resolve the issue.”

To avoid duplicating them and having to keep them updated, I simply inject them into the application before a new connector is cloned.

Application application = context.getObjectByName(Application.class, applicationName);

ArrayList persistentArrayList = application.getAttributeValue("domainSettings");
Map domainSettings = persistentArrayList.get(0);

application.setAttribute("authorizationType", domainSettings.get("authorizationType"));
application.setAttribute("host", domainSettings.get("servers").get(0));
application.setAttribute("password", domainSettings.get("password"));
application.setAttribute("port", domainSettings.get("port"));
application.setAttribute("user", domainSettings.get("user"));

Connector connector = sailpoint.connector.ConnectorFactory.getConnector(application, null);

Original Fix (from comment above)

Aggregating a single account from an application