- Overview
- Setting account status vs. setting identity status
- How identities are made inactive
- Sourcing an green/red icon for accounts enabled or disabled
Overview
IdentityIQ supports two concepts of user objects being disabled:
- Accounts (sailpoint.object.Link) can be represented as disabled.
- Identities (sailpoint.object.Identity) can be represented as disabled.
These concepts are related, but very independent. Usually the active or inactive state of one or more accounts from Applications marked as "authoritative" in IdentityIQ is used to drive or populate the active or inactive state of the Identity cube. To understand the complexities of disabling Accounts and Identities, it’s useful to be clear on the differences between regular accounts and “authoritative” accounts, as well as how source applications typically track a user’s state of activity or inactivity:
- In general, regular accounts (like a user’s Active Directory account, or accounts on mainframes or Unix/Linux servers) typically reflect simply the local status of that account. If the account is enabled, then the user can login to that system. If the account is disabled then the user can’t login.
- Authoritative accounts, however (that is, accounts read from “authoritative sources”) usually come from HR management systems like Workday, PeopleSoft, or contractor management systems. Account status on these systems typically reflects an across-the-board active or inactive status for the individual.
Often HR management systems don’t have a binary concept of “active” or “inactive,” but instead have a concept of “employment status”. Common employment statuses are often modeled with one-letter codes like “A” (actively employed), “B” (on disability leave), “E” (former employee deceased), “L” (on disciplinary or sabbatical leave), “M” (on military leave), or “T” (employee terminated and no longer with the organization). Several different permutations exist and different HR management systems and different legal jurisdictions handle all of these concepts slightly differently.
IdentityIQ can read these employment status fields and reflect them in its user interface, but doesn’t natively grasp the differences between each. It is the job of the deployment professional to create a site-specific mapping from the different HR management system's employment status values to IdentityIQ's enabled/disabled status. The employment status is usually represented verbatim in the account model read from the authoritative application in the user interface, but the translation of which employment status values map to the concept of an enabled or disabled Identity is a site-specific policy. In effect IdentityIQ must be configured with a mapping that "blurs down" the many statuses of an individual down to a Boolean value of "inactive or "active".
Setting account status vs. setting identity status
The way to set an Account's disabled status is to populate the "IIQDisabled" special schema attribute, as shown in the customization rule example shown below. This will set the enabled/disabled status of the account's Link record in IdentityIQ, and allows to use the method link.isDisabled(). Most of the "direct" or "provisioning enabled" connectors will do this for automatically you; for example, Active Directory will automatically set the IIQDisabled status based on the values read from the "userAccessControl" field of the account record. Other connectors, like LDAPs or PeopleSoft or Workday behave similarly.
You always have the option to use the "IIQDisabled" approach in a Customization rule for a connector if you need site-specific behavior, or do not want to leverage the functionality compiled into the connector. When configuring custom JDBC-based connectors or delimited file based connectors, the author of the Application XML is responsible for providing a Customization rule or Build Map rule that populates the "IIQDisabled" property. Here is an example code snippet from a Customization rule setting the "IIQDisabled" attribute of an account during account aggregation:
import org.apache.log4j.Logger;
import org.apache.log4j.Level;
// Declare a logger class for us to isolate these messages during aggregation.
Logger log = Logger.getLogger("sailpoint.services.ldapCustomizationTest");
log.setLevel((Level) Level.DEBUG); // TODO: Remove debug logging in production use.
String acctName = object.getIdentity();
// If job title has been populated with "TERMINATED" set the account to disabled.
String titleString = object.getAttribute("title");
if ( (null != titleString) && (0 != titleString.length()) ) {
if ("TERMINATED".equalsIgnoreCase(titleString)) {
object.put("IIQDisabled", true);
log.debug("The 'title' set to terminated on [" + acctName + "], marking IIQDisabled as true.");
}
} else {
log.debug("No 'title' field populated on [" + acctName + "], assuming active account.");
}
return object;Note: For details about how to use the "IIQDisabled" attribute when configuring connectors and aggregation, see the following KB article: BSDG 13 - Aggregation Rule Best Practices .
The way to set an Identity's disabled status is much more complicated. The concept of an Identity being disabled is usually driven by the idea that a human resources department considers the employee or contractor to be terminated or no longer a part of the organization.
How identities are made inactive
An Identity's enabled/disabled status is stored on the "inactive" attribute of the Identity's record (sailpoint.object.Identity). IdentityIQ defaults to assuming Identity records are "active" (or, more accurately, "not inactive"). If you look at an Identity's XML in the Debug page of the product and do not see an attribute called "inactive" then IdentityIQ assumes a value of "inactive = false", which means the Identity is considered active. For an Identity record to be considered inactive/disabled the "inactive" attribute must be present in the Identity's attributes map and set to a value of "true".
The "inactive" attribute of the Identity cube is populated during an Identity Refresh task when the "Refresh identity attributes" option is selected. The "inactive" attribute of the Identity cube might be populated during an Account Aggregation task that includes authoritative applications, but the field is not generally populated during any specific account aggregation. The reason for this is fairly simple: most installations require relatively complex logic to evaluate whether or not an identity should be considered active or inactive inside the organization.
For example, in most organizations there is a pathway for certain employees to start their career with the organization as contractors and eventually become full-time employees. This means that individuals may have multiple human resources application accounts ("authoritative source" accounts) correlated to their identity. Alternatively, in cases where an organization maintains multiple authoritative accounts, individuals may have a record in, for example, the "contractors" management system as well as records in the "employees" management systems in scenarios where the systems are different applications. The logic for how to calculate and determine whether an individual is active or inactive is largely site-specific, and this is why IdentityIQ allows deployment professionals to implement site-specific Rule code that reflects the organizations policies on what is active and inactive.
The simplest method for configuring how an Identity record's active status is populated is to use a direct "Application Attribute" setting for "Source Mapping" for the "inactive" attribute. This can be seen in IdentityIQ versions 6.4 and earlier under "System Setup -> Identity Mappings -> Inactive" and on IdentityIQ 7.0 and newer systems under "Setup Gear -> Global Settings -> Identity Mappings -> Inactive". Deployment professionals for IdentityIQ working on their first few projects usually map the HR application's active/inactive status to the Identity's active and inactive status and if there is a contractor account record.
Unfortunately this configuration, which looks like the obvious way to configure it and works for most employees, is insufficient and does not provide the correct behavior in all cases. Application attribute mapping without using Rule code only works as expected when there is a single authoritative source being used for both employees and contractors, and when it is guaranteed that in the data feed that an employee or contractor will always have one and only one account or record from that connector.
Let's look at an example for an imaginary employee named "Jane", who has a very common work story: Jane worked for the company as a full time employee and then left the company when she decided to start a family. After having some children, Jane returned as a part-time contractor, working reduced hours during the week while the children were little. After a year or two, Jane returned to being a full time employee for the company. In this scenario, Jane might have 3 account records from the authoritative source applications. Here's an example of what these account records might look like:
app:HR-EMP acctName:Jane status:T effectiveDate:2009-10-13
app:HR-CWR acctName:Jane status:T effectiveDate:2013-12-31
app:HR-EMP acctName:Jane status:A effectiveDate:2014-01-02From these records we can see Jane had an account in HR as an Employee where she was terminated in 2009. Then she has an account as an account in the CWR (contingent worker/contractor) system that was terminated in 2013. Finally, she has an account in the Employee system showing her as an active employee, beginning in 2014.
Using IdentityIQ's "Application Attribute" option of "Source Mappings" feature for setting Jane's state is not sufficient to handle this very common scenario. If an "Application Attribute" based Source Mapping is used here, then the active/inactive state of the "most recently aggregated account" will be what gets pushed up to Jane's Identity record. If HR is aggregated on Monday and Jane's terminated account happens to be the later record processed by the aggregation, then Jane's Identity cube will show a terminated status. If the reverse happens, then Jane's cube will show an active status. If every day we schedule the contractor system to aggregate immediately after the employee system, then Jane's cube will always show terminated, which is certainly not what we want. The mechanics of the way optimized and delta aggregations work in IdentityIQ can obscure the fact this this setup is really an improper configuration of IdentityIQ.
For IdentityIQ to correctly model the active/inactive nature of Jane's identity, we must use a Rule - either an Application-specific rule associated with each authoritative source, or a "Global Rule (all applications)". The use of the Rule lets us specify how to handle the population of the "inactive" Identity attribute. This rule can implement the correct logic to compute whether Jane's identity is truly active or not. The rule is a rule of type "IdentityAttribute", which takes several arguments it can use to evaluate the new attributeValue it is calculating. Most often these rules load the set of accounts (sailpoint.object.Link objects) and use their details to make the final decision. The pseudo-code for what this rule might look like is provided here as an introductory example:
// Default to assuming all Identities are disabled, unless an authoritative source tells us otherwise.
boolean inactiveVal = true;
// Pseudo code, real Beanshell/Java code will look different!
if (identity.has an active EMP link && the active EMP link's effectiveDate is the most recent) {
inactiveVal = false;
log.debug("Setting identity " + identity.getName() + " to active from EMP account: " + link.getNativeIdentity());
}
if (identity.has an active CWR link && the active CWR link's effectiveDate is the most recent) {
inactiveVal = false;
log.debug("Setting identity " + identity.getName() + " to active from CWR account: " + link.getNativeIdentity());
}
return inactiveVal;The Identity attribute promotion function is what sets the "inactive" attribute (and all other attributes) of the Identity record. This is usually set during Identity Refresh operations. When an Application Sourced mapping rule is used, then IdentityIQ will evaluate the rule during the aggregation of the account. The use of logging statements as described here (BSDG 2 - Using Apache Log4J in Bean Shell ) can help the you observe exactly when the Rule executes during an Identity Refresh or Account Aggregation. The pseudo-code shows a best practice of including log messages that show the Identity's name and why a decision is being made.
Sourcing an green/red icon for accounts enabled or disabled
IdentityIQ can be configured to display icons illustrating the enabled or disabled state of Accounts in screens listing accounts (e.g. in Define -> Identity -> Account tab, in Define -> Application -> Account tab).
This is configured by adding entries into the UIConfig object (for version 6.x / 7.0):
<UIConfig ...>
<Attributes>
<Map>
...
<entry key="accountIconConfig">
<value>
<List>
...
<AccountIconConfig attribute="myInactiveAttribute" source="/images/icons/certif_approved_16.png" title="Account Enabled" value="false"/>
<AccountIconConfig attribute="myInactiveAttribute" source="/images/icons/certif_rejected_16.png" title="Account Disabled" value="true"/>
</List>
</value>
</entry>
...
</Map>
</Attributes>
</UIConfig>
In this example, myInactiveAttribute is the case sensitive name of the extended attribute defined in Account Mapping, which should be storing exactly “true” or “false” for all the Links, any other value (including empty) means no icon is mapped so no icon would appear near the account. For the engine to use this configuration, the Account attribute must be configured with one or more source mapping: as example one Source mapping for each application that supports account enable/disable (note that some target application like Unix OS accounts do not have any enable/disable capability).
e.g.: in the below example, myInactiveAttribute has two source mapping from Financials and PRISM application, hence only these application accounts have a chance to have an icon
==> 
Finally, in the above configuration, the icon is related to the extended Account attribute "myInactiveAttribute", this is a property different than IIQDisabled. Nothing out-of-the-box in IdentityIQ prevents myInactiveAttribute and IIQDisabled to have inconsistent value (one could be true while the other can be false). In this situation it is up to the implementer to ensure that all properties reflecting a status are kept consistent to each other through rules executed during Aggregation (as example) or in case of updates.
