Aggregating a single account from an application

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

chris_panton · ‎Jan 14, 2016

Thanks for this document it is very helpful - however I have one question. I have implemented the api based approach and it is working well. However I want to be able to point the aggregation to a specific domain controller as this is being used just after provisioning active directory and replication will not have happened yet on the AD side so I need to point it to the dc used in provisioning. There is a very useful article that we have used to handle this in general for provisioning however I have tried various things to be able to control which dc this api based aggregation runs on but have so far not found a way to pass in the dc to the aggregation and have it use that one. Do you know if there is a way to achieve this.

adam_hampton · ‎Jan 14, 2016

Hi Chris,

Welcome to the joys of multi-server race conditions. The AD connector doesn't support directing a request at a specific DC host, unless you bind all IdentityIQ operations to that DC host. The best way to handle this today is to delay your re-aggregation a small number of seconds, usually around 15 works, until you are certain your DC hosts have replicated the change.

--Adam

sean_flynn · ‎Feb 10, 2016

Thanks for posting this, I'm currently attempting to run it in IdentityIQ 7.0 and I am getting this error when I attempt to perform a single aggregation on AD:

The application script threw an exception: sailpoint.connector.AuthenticationFailedException: Failed to connect to server:Required String attribute : authorizationType value was null.

It appears to me like it is expecting a value in the base of the xml not under the Domain Settings as the authorizationType is available there. Any ideas on what I need to do to get around the issue? I've tried adding in the authorizationType at the root level, but then it complains about the host being null. Guess I can keep adding attributes to the root of the xml and see what happens. All insight welcome. Thanks.

Sean

adam_hampton · ‎Feb 10, 2016

Are you able to do a normal aggregation against your AD application successfully? What's the "authorizationType" attribute set to inside or AD Application's XML? It's usually set to something like "simple", like this:

...

<value>

<List>

<Map>

...

--Adam

sean_flynn · ‎Feb 10, 2016

Yes, normal aggregations are working fine in AD. It is odd that it can't seem to find authorizationType under the DomainSettings. If I add in the attribute at the root of the xml the error goes away.

adam_hampton · ‎Feb 10, 2016

My example came from a 6.4p4 system, maybe that DTD changed in 7.0.

Travis-Kroeten · ‎Feb 11, 2016

Thanks for this article, super helpful.

Question though. We're using the programmatic approach as part of an AD Mover workflow where we're changing the nativeIdentity (distinguishedName) of the user's account link. This does a good job of picking up the "new" account (the one with the updated nativeIdentity), but obviously doesn't get rid of the old account link. Right now we just have an identity refresh step in the workflow with refreshLinks="true" to get rid of it. Is there a more efficient way we could be doing this that you can think of?

-Travis

adam_hampton · ‎Feb 11, 2016

Yes, you can assemble a ResourceObject to model the old account link and set the isDeleted() property of the Resource Object to "True". Then you can pass that to the Aggregator with an option for "checkDeleted" set to true. This will cause IdentityIQ to process that account as deleted and remove the old link. This will be faster and more atomic than asking the Identitizer to re-aggregate all of the links that the user has.

--Adam

georgiana_mateescu · ‎Feb 24, 2016

Hi,

Thanks for this helpful document. I am using a 6.4.p4 system, and i receive the same error when trying to aggregate a single account from AD:

"The application script threw an exception: sailpoint.connector.AuthenticationFailedException: Failed to connect to server:Required String attribute : authorizationType value was null. It must have a valid value".

Did you find any solutions for this?

sean_flynn · ‎Feb 24, 2016

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. Hope that helps.

Aggregating a single account from an application