SSF Tools Logi Plex Connector User Guide

User Manual:

Open the PDF directly: View PDF .
Page Count: 14

Download
Open PDF In Browser	View PDF

SSF Tools: IdentityIQ LogiPlex
Connector User Guide
LogiPlex Connector: IdentityIQ 7.0, 7.1+

This document explains the inner workings, installation and use of the LogiPlex Connector. The
LogiPlex Connector is a special connector that provides functionality like the standard Logical
connector and multiplex applications.

Document Revision History
Revision
Date
April 2018

Written/Edited By

Comments

Menno Pieters

Initial Release

© Copyright 2018 SailPoint Technologies, Inc., All Rights Reserved.
SailPoint Technologies, Inc. makes no warranty of any kind with regard to this manual, including, but not limited to, the implied
warranties of merchantability and fitness for a particular purpose. SailPoint Technologies shall not be liable for errors
contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing,
performance, or use of this material.
Restricted Rights Legend. All rights are reserved. No part of this document may be photocopied, reproduced, or translated to
another language without the prior written consent of SailPoint Technologies. The information contained in this document is
subject to change without notice.
Use, duplication or disclosure by the U.S. Government is subject to restrictions as set forth in subparagraph (c) (1) (ii) of the
Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 for DOD agencies, and subparagraphs (c)
(1) and (c) (2) of the Commercial Computer Software Restricted Rights clause at FAR 52.227-19 for other agencies.
Regulatory/Export Compliance. The export and reexport of this software is controlled for export purposes by the U.S.
Government. By accepting this software and/or documentation, licensee agrees to comply with all U.S. and foreign export laws
and regulations as they relate to software and related documentation. Licensee will not export or reexport outside the United
States software or documentation, whether directly or indirectly, to any Prohibited Party and will not cause, approve or
otherwise intentionally facilitate others in so doing. A Prohibited Party includes: a party in a U.S. embargoed country or country
the United States has named as a supporter of international terrorism; a party involved in proliferation; a party identified by the
U.S. Government as a Denied Party; a party named on the U.S. Government's Entities List; a party prohibited from
participation in export or reexport transactions by a U.S. Government General Order; a party listed by the U.S. Government's
Office of Foreign Assets Control as ineligible to participate in transactions subject to U.S. jurisdiction; or any party that licensee
knows or has reason to know has violated or plans to violate U.S. or foreign export laws or regulations. Licensee shall ensure
that each of its software users complies with U.S. and foreign export laws and regulations as they relate to software and
related documentation.
Trademark Notices. Copyright © 2018 SailPoint Technologies, Inc. All rights reserved. SailPoint, the SailPoint logo, SailPoint
IdentityIQ, and SailPoint Identity Analyzer are trademarks of SailPoint Technologies, Inc. and may not be used without the
prior express written permission of SailPoint Technologies, Inc. All other trademarks shown herein are owned by the
respective companies or persons indicated.

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 2 of 14

Table of Contents
LogiPlex Connector Overview ................................................................................................................ 4
1.

Introduction ................................................................................................................................. 4

2.

Application Details ....................................................................................................................... 5
2.1.

3.

Application Type ................................................................................................................. 5

Terminology ................................................................................................................................ 5
3.1.

Master Application .............................................................................................................. 5

3.2.

Main Application ................................................................................................................. 5

3.3.

Sub Application .................................................................................................................. 5

3.4.

Inner Working ..................................................................................................................... 6

Installation and Configuration................................................................................................................. 7
4.

Installation Files .......................................................................................................................... 7

5.

Configuration ............................................................................................................................... 7
5.1.

Settings .............................................................................................................................. 7

5.2.

Rules .................................................................................................................................. 8

5.2.1.

LogiPlex Split Rule.......................................................................................................... 8

5.2.1.1.

Description .............................................................................................................. 8

5.2.1.2.

Definition and Storage Location .............................................................................. 8

5.2.1.3.

Arguments .............................................................................................................. 8

5.2.1.4.

Example .................................................................................................................. 9

5.2.2.

LogiPlex Provisioning Rule ........................................................................................... 10

5.2.2.1.

Description ............................................................................................................ 10

5.2.2.2.

Definition and Storage Location ............................................................................ 11

5.2.2.3.

Arguments ............................................................................................................ 11

5.2.2.4.

Example ................................................................................................................ 11

6.

Schema Attributes ..................................................................................................................... 12

7.

Provisioning Policies ................................................................................................................. 12

Miscellaneous ...................................................................................................................................... 13
8.

Known Issues ............................................................................................................................ 13
8.1.

Test Connection ............................................................................................................... 13

8.2.

Aggregation of Sub-Applications....................................................................................... 13

8.3.

Partitioning ....................................................................................................................... 13

8.4.

Version 7.1 versus 7.2 ...................................................................................................... 14

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 3 of 14

LogiPlex Connector Overview
This document explains what the LogiPlex connector is, its inner workings, installation and usage. The
LogiPlex Connector is a special connector that provides functionality which is a mixture of the standard
Logical connector and multiplex applications.

1. Introduction
The LogiPlex Connector is a possible alternative for logical applications, using features of the multiplex
application type. The name of this connector is composed of the connector types that inspired the
creation: the logical and the multiplex connector types.
From the Direct Connectors Administration and Configuration Guide:

The SailPoint Logical Connector is a read only connector developed to create
objects that function like applications, but that are actually formed based on
the detection of accounts from other, or tier, applications in existing identity
cubes.
For example, you might have one logical application that represents three
other accounts on tier applications, an Oracle database, an LDAP
authorization application, and a custom application for internal authentication.
The logical application scans identities and creates an account on the logical
application each time it detects the three required accounts on a single
identity.
You can then use the single, representative account instead of the three
separate accounts from which it is comprised for certification, reporting, and
monitoring.
The Logical Connector has a number of performance drawbacks: it requires information to be
aggregated and then iterates over identities to find suitable matches. This is often a very timeconsuming task. The LogiPlex Connector tries to overcome these issues by processing logical
applications on the fly, during aggregation. This approach allows the use of performance-enhancing
connector features like partitioning, optimized aggregation and delta aggregation.
The Logical Connector acts as a wrapper around any normal connector. It must be set up to point to a
pre-configured application and will use all features of the target application for aggregation and
provisioning. It uses two additional rules to process information when aggregating and provisioning
account or group information.
When aggregating, account and group information is enriched with additional attributes to indicate the
name of the logical sub-application. This mechanism is the same as used for so called multiplex
applications.

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 4 of 14

A possible downside of the LogiPlex Connector is that it may be harder to set up than a standard
Logical Connector. The LogiPlex Connector requires more BeanShell coding to work than most Logical
Connector configurations. For the Logical Connector the tiers can be configured by just selecting the
relevant entitlements. Furthermore, the LogiPlex Connector is less suitable for combining information
from multiple tiers, although the aggregation split rule can be used to perform side lookups.

2. Application Details
2.1.

Application Type

The application type is “LogiPlex Connector”.

3. Terminology
In this document, we will use three different terms for the application definitions involved in the
aggregation and provisioning of LogiPlex data.

3.1.

Master Application

The master application is a standard application, like a directory server (LDAP, Active Directory), a
database or delimited file application. This application needs to be set up first and proven to be working
correctly.

3.2.

Main Application

The main application is the base LogiPlex application. The Main Application will be configured to point
to the Master Application and use the connector defined in the Master Application to perform the actual
work.

3.3.

Sub Application

A Sub Application is any application derived from the Main Application, based on information read from
accounts. Unless the aggregation task is configured to prevent this, Sub Applications will be generated
on the fly, while aggregating data.
A Sub Application will have the Main Application defined as a Proxy.

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 5 of 14

Figure 1: Relations between application definitions and connectors

3.4.

Inner Working

The idea behind this connector is that we would like to use multiplex-like behavior to achieve the logical
account grouping that a Logical Connector provides: sub-applications of a master application. As an
example, consider two sets of groups in a directory server giving access to a web application and a
server application.
A multiplex application only allows an account to be redirected to a single sub-application, while we
would like the same account to be related to the web application as well as the server application,
listing only the relevant group memberships.
The LogiPlex Connector features a rule option that allows inspection of a freshly read account or group
object (ResourceObject) and return one or more slightly modified instances of this object in a map.
The LogiPlex Connector uses a special iterator class that wraps the iterator of the original connector
but uses the split rule to retrieve the sub-application accounts.

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 6 of 14

Installation and Configuration
4. Installation Files
If you are deploying IdentityIQ 7.2 or greater with the Services Standard Deployment (SSD), the
LogiPlex Connector will be deployed by default, and there are no extra steps to take to install it.
Deployment is controlled by this property in the build.properties file:
deployLogiPlexConnector=true

Setting it to false will prevent the connector being deployed.
The IdentityIQ LogiPlex Connector consists of the following Java class files:
Filename
LogiPlexConnector.java

Description
Main LogiPlex Connector Java class

The configuration files are:
Filename
ConnectorRegistry-LogiPlexConnector.xml

Description
Connector registry merge file to describe
the connector.

The configuration interface files, placed under define/applications/ are:
Filename
logiPlexAttributes.xhtml
logiPlexAttributesInclude.xhtml
logiPlexRulesForm.xhtml

Description
Base configuration
Additional attribute configuration
Connector Rules configuration

Some sample rules are also provided in the SSD under the folder
config/SSF_Tools/LogiPlex_Connector/Samples. These will not be deployed by default.

5. Configuration
5.1.

Settings

The connector has just two configuration settings:
Setting
Master Application

Type
Application

Split Application Prefix

String

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Description
The application definition which defines the
connector of the real target application
If set, every application selected by the split
rule on aggregation will be prefixed with

Page 7 of 14

this string. If the string does not end in a
dash, a dash will be added as a separator.
E.g. if the prefix is set to “LGX”, the subapplication “Expenses” will become
“LGX-Expenses”. If the prefix is set to
“ABC-”, it will become “ABC-Expenses”
Connection settings must be configured on the master application.

5.2.

Rules

The connector has two additional rules options. Since we cannot extend the types of rules supported by
IdentityIQ, as rule types are defined as an enum, we have to re-use existing rule types.

5.2.1. LogiPlex Split Rule
5.2.1.1.

Description

The LogiPlex Split Rule is in fact a rule of type ResourceObjectCustomization, but is run before the
actual customization rule is applied. It will receive slightly different inputs and the expected output is
also different.
5.2.1.2.

Definition and Storage Location

The rule is associated to a LogiPlex application in the UI in the application definition:
Application →Application Definition → select existing or create new application → Rules →
LogiPlex Split Rule
5.2.1.3.

Arguments

Inputs
Argument
object

Type
sailpoint.object.ResourceObject

application
applicationName
connector
state

sailpoint.object.Application
java.lang.String
Not provided
java.util.HashMap

Purpose
A reference to the resource
object built by the connector

The name of the application.
A Map that can be used to store
and share data between
executions of this rule during a
single aggregation run.
map
java.util.HashMap
A pre-prepared map to be filled
>
and returned
util
sailpoint.services.standard.connector. An instance of the LogiPlexUtil
LogiPlexConnector.LogiPlexUtil
as used by the iterator, to allow
calling convenience methods
(see JavaDoc for the connector).
Note: contrary to a normal customization rule, the connector variable is not set.

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 8 of 14

Outputs
Argument
objects

5.2.1.4.

Type
java.util.HashMap

Purpose
A Map containing application
names as keys and
corresponding ResourceObject
values.

Example

This example rule will inspect the account and group objects received from an LDAP server. It will
check the name of group memberships. Groups starting with cn=webapplication will be related to
the WebApplication application. Groups starting with cn=expenses- will be related to the Expenses
application. All other groups will be related to the main application. In this example, the choice has been
made to also return results for the main application, although this is not required.
import sailpoint.tools.Util;
import sailpoint.object.ResourceObject;
public String resolveApplication(String name) {
if (Util.isNotNullOrEmpty(name)) {
String lname = name.toLowerCase();
if (lname.startsWith("cn=webapplication")) {
return "WebApplication";
}
if (lname.startsWith("cn=expenses-")) {
return "Expenses";
}
}
return application.getName();
}
String applicationName = application.getName();
Map map = new HashMap();
if ("account".equals(object.getObjectType())) {
List groups = object.getStringList("groups");
if (groups != null && !groups.isEmpty()) {
Map groupMap = new HashMap();
groupMap = util.updateListMap(groupMap, applicationName, null);
for (String group: groups) {
String appName = resolveApplication(group);
if (Util.isNotNullOrEmpty(appName)) {
groupMap = util.updateListMap(groupMap, appName, group);
}
}
Set keys = groupMap.keySet();
if (!keys.isEmpty()) {
for (String key: keys) {
List appGroups = groupMap.get(key);
ResourceObject cloneObject = object.deepCopy(context);
if (!Util.isEmpty(appGroups)) {
cloneObject.put("groups", appGroups);
} else {
cloneObject.remove("groups");
}
map.put(key, cloneObject);
}

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 9 of 14

} else {
map.put(applicationName, object);
}
} else {
map.put(applicationName, object);
}
} else if ("group".equals(object.getObjectType())) {
String nativeIdentity = object.getIdentity();
String appName = resolveApplication(nativeIdentity);
map.put(appName, object);
} else {
map.put(applicationName, object);
}
return map;

In case a large number of groups need to be considered, good alternatives to check for the destination
of groups could be:
•
•

A Custom object containing the names or regular expressions to match,
Additional information on groups in the source application: aggregate groups first to populate
the Entitlement Catalog, then reference the entitlement catalog to determine to which
application(s) a group should be linked.

5.2.2. LogiPlex Provisioning Rule
5.2.2.1.

Description

The LogiPlex Provisioning Rule is in fact a rule of type CompositeRemediation (Logical Provisioning
Rule). It accepts a provisioning plan and can modify the plan for the real target application and then
return the modified provisioning plan.
If the rule is not provided, the connector will apply internal default logic. This default logic will:
•
•
•

Clone the plan and included AccountRequest and ObjectRequest objects.
For each request object targeted at the main application, just keep the request as is.
For each account request object targeted at a sub application:
o Handle create operation as create operations only if there is no corresponding account
on the main application,
o Handle create operations as modify operations, applicable only to entitlements, if there
already is a corresponding account on the main application,
o Handle deletion on a sub-application as a removal for all entitlements,
o Handle changes on sub-application accounts only for entitlements,
o Handle enabling, disabling, locking and unlocking only on the main application (ignore
for sub-applications).

NOTE: When deleting, enabling, disabling, locking or unlocking the main application account, the same
operation is applied to sub-application. This is handled after the provisioning plan has been executed
and applied internally only.

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 10 of 14

NOTE: Most often, the rule will clone the original plan and modify the included AccountRequest objects.
Note that for these objects and the enclosed AttributeRequest objects, it is important to also copy any
arguments, as these may be necessary to link information back to its origins after provisioning.
5.2.2.2.

Definition and Storage Location

The rule is associated to a LogiPlex application in the UI in the application definition:
Application →Application Definition → select existing or create new application → Rules →
LogiPlex Provisioning Rule
5.2.2.3.

Arguments

Inputs
Argument
identity

Type
sailpoint.object.Identity

plan

sailpoint.object.ProvisioningPlan

application

sailpoint.object.Application

masterApplication

sailpoint.object.Application

connector

sailpoint.connector.AbstractConnector

masterConnector

sailpoint.connector.AbstractConnector

Purpose
Reference to the Identity
object for whom the
provisioning request has
been made
Reference to a provisioning
plan against the LogiPlex
application
The LogiPlex application
definition
The master application
definition
An instance of the LogiPlex
connector
An instance of the
connector for the master
application

Outputs
Argument
plan
5.2.2.4.

Type
sailpoint.object.ProvisioningPlan

Purpose
The modified plan

Example

The goal of this rule is to merge changes for sub-applications into the main application. It is important to
understand that the plan will, after successful provisioning, also be applied to the identity cube. So, the
plan must be modified in such a way that whatever will change ends up in the original plan object.
The easiest implementation is by calling the default logic on the main application, which is
demonstrated below. After doing that, it is possible to make some additional changes to the plan.
import sailpoint.object.ProvisioningPlan;
import sailpoint.services.standard.connector.LogiPlexConnector;
// Expect: sailpoint.connector.AbstractConnector connector

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 11 of 14

// Use the default logic from the connector to re-compose the plan.
ProvisioningPlan newPlan = ((LogiPlexConnector)
connector).runDefaultProvisioningMergeLogic(plan, identity);
// After using the default logic, optionally, other changes could be applied.
if (log.isTraceEnabled() && newPlan != null) {
// Dump the plan.
log.trace(newPlan.toXml());
}
return newPlan;

6. Schema Attributes
The schema(s) can either be generated from the master application or entered manually. To generate
the schema(s) from the master application, use the Discover Schema Attributes for each object type.

7. Provisioning Policies
Provisioning policies will, unfortunately, not be copied from the master application to the LogiPlex
application. The provisioning policy or policies will have to be re-configured or copied as XML in the
Debug interface.
If the provisioning policy for the master application is setup as a separate Form object, both the master
and the LogiPlex application can reference the same Form object.

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 12 of 14

Miscellaneous

8. Known Issues
8.1.

Test Connection

When clicking the Test Connection button, an error will appear along with a success message.

Figure 2: Error during Test Connection

This specific error message can be ignored. The connector works just fine. Other errors may indicate
an issue with the setup or the configuration of the Master application.

8.2.

Aggregation of Sub-Applications

Like with a multiplex application, aggregation should be performed only on the main application.
Aggregating directly from a sub-application may not have the desired outcome, depending on how rules
are setup.

8.3.

Partitioning

Dividing partitions only works correctly if the connector natively supports partitioning. Application level
partitioning will work, but the numbers used to divide the partitions will be off. When calculating the
number of partitions, the master application will return the raw number of accounts. When the split rule
is applied, the number of accounts may be a lot higher.
As shown in the picture below, the number of aggregated accounts is already higher than the expected
number of accounts per partition. In this example, we are aggregating a delimited file with 100,000
lines, corresponding to 100,000 accounts.
If partitioning is configured to create 4 partitions, like in this example, it expects to aggregate 25,000
accounts per partition. The LogiPlex Split Rule may return multiple accounts (main and sub) for each
line read.

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 13 of 14

Figure 3: Results for Application Level Partitioning

8.4.

Version 7.1 versus 7.2

There is minor difference between version IdentityIQ 7.1 and 7.2 that requires a small change in the
connector code when moving between the versions. The class ExpiredPasswordException has
been moved from the package sailpoint.api to sailpoint.connector in 7.2.
So, IdentityIQ 7.1 needs this import:
import sailpoint.api.ExpiredPasswordException;

And IdentityIQ 7.2 needs this import:
import sailpoint.connector.ExpiredPasswordException;

If you are using the SSD to create your build, the source code modification will be done by the build
scripts and you will not need to change anything.

SSF Tools: IdentityIQ LogiPlex Connector User Guide

Page 14 of 14



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.7
Linearized                      : No
Page Count                      : 14
Language                        : en-US
Tagged PDF                      : Yes
XMP Toolkit                     : 3.1-701
Producer                        : Microsoft® Word 2016
Creator Tool                    : Microsoft® Word 2016
Create Date                     : 2018:06:01 15:20:18+00:00
Modify Date                     : 2018:06:01 15:20:18+00:00
Document ID                     : uuid:28A3BDB0-E5B4-4A12-BBB7-309DED0C906B
Instance ID                     : uuid:28A3BDB0-E5B4-4A12-BBB7-309DED0C906B
Creator                         : Microsoft® Word 2016

EXIF Metadata provided by EXIF.tools