Integrating with an LDAP Directory

Many organizations have established a central repository (a directory service) for user and group information, making it possible to edit that information independently from all the different systems that need it. However, iKnowBase needs a local copy of that information in order to support security and context operations.

Use the Advanced LDAP Synchronization (formerly known as Advanced OID Synchronization) component in iKnowBase Development Studio to set up a replication link, where information automatically flows into iKnowBase when the directory service changes it.

Understanding LDAP synchronization

During user synchronization, the synchronization engine will periodically read the LDAP changelog to understand what kind of changes have happened in the source user directory.

The changelog will contain entries indicating that users, groups or group memberships have changed. The synchronization engine will use its configuration to copy these changes into the corresponding iKnowBase objects.

• For more information on synchronizing a person, see Synchronize a Person.
• For more information on synchronizing an organization, see Synchronize an Organization.
• For more information on pre user synchronization and post user synchronization, see Pre and Post User Synchronization.
• For more information on optional attributes, see Optional Attributes.

Synchronizing users

This chapter describes the options that control what happens when the LDAP changelog contain a user object. The options include

• Create user objects, such as an iKnowBase user, a user dimension and a person card
• Create organization objects, such as an iKnowBase group and an organization card
• Define optional attribute mappings for the person and organization cards
• Specify PL/SQL procedures to run at defined points in the process.

User objects

When the changelog specifies changes to a person in the LDAP directory, the user synchronization engine will create or update iKnowBase information. The creation and updates to this information is managed by information from the synchronization profile:

• Every user has a user object in the iKnowBase user table:
  • On tab two, “person card mapping” specify which LDAP-attributes contain username, e-mail and display for the user object itself. You must enter valid values corresponding to your environment; typical values can be “UID”, “MAIL” and “displayName” respectively.
  • On tab one, “default ikb group” specifies an iKnowBase group that the user will e added to.
• Further, every person has a personal dimension, an iKnowBase information object for that particular person:
  • On tab one, “Top dimension (person)” defines the iKnowBase dimension under which the personal dimension is created
  • On tab one, “Dimension type” defines the type of dimension which is createdgr
• Further, every person has a “person card”, an iKnowBase information object describing the user. The creation of this card is managed by other information from the synchronization profile
  • On tab one, “Document type (person card)” defines the iKnowBase information object type used when creating the person card.
  • On tab one, “additional attributes” specify a list of LDAP-attributes that will be added to the person card during creation or update
  • On tab one, “default access group” specifies the ACL used for the person card.

Organization objects

A user entry in LDAP typically contains some sort of information that identifies the organization unit that the user belongs to, such as his department or section.

The iKnowBase LDAP Synchronization engine is capable of automatically creating iKnowBase object corresponding to the organization. Check the relevant checkboxes on tab two to specify these:

• You may create an iKnowBase group, with all users with the same organization attribute as members;
  • On tab two, check the box "create ikb group"
• You may create a “organization card” for the organization, and iKnowBase information object describing the organization:
• On tab two, check the box "create org. card"

Optional Attributes

The default synchronization will add only key information such as name and external key to the user and organization cards. On tab two, you may choose to add extra attributes to both of these cards, with values from available attributes of the LDAP user object.

Pre and Post Plug-Ins

In the case of users, there can be issues related to synchronization that are not resolved in the configuration interface. For example, all the users in an organization have an e-mail address in the employeenumber@company.com format. In this case, customer cannot use the standard configuration interface to map the employee number to an iKnowBase attribute.

You can specify the functions that run the pre user synchronization and post user synchronization to iKnowBase. These functions take some parameters to make changes to the objects that are related to the user synchronization.

The interface provides a plug-in in which the developer can write a code and use this code as a plug-in to the synchronization application. The synchronization application supports two plug-ins, the preUserSynch and postUserSynch plug-ins.

Pre user synch plug-in

The preUserSynch plug-in is called before the synchronization takes place in iKnowBase. The postUserSynch plug-in is called after the actual synchronization takes place in iKnowBase.

The signature of the plug-in is:

CREATE OR REPLACE PROCEDURE preuseradd (
   p_profile_name   	IN       VARCHAR2,
   p_dn             	IN       VARCHAR2,
   p_ldap_conn      	IN       DBMS_LDAP.SESSION,
   p_changetype         IN       VARCHAR2,
   p_entrytype		IN      VARCHAR2, (PERSON, GROUP, DELETE)
   p_cn			IN 	VARCHAR2,
   p_continue       	OUT     NUMBER
   p_do_create_card 	OUT     NUMBER
)

Post user synch plug-in

The postUserSynch plug-in is called after the user, the organization card, and the person card is created in iKnowBase.

The signature of the plug-in is:

CREATE OR REPLACE PROCEDURE postuseradd (
   p_profile_name   	IN   VARCHAR2,
   p_dn             	IN   VARCHAR2 DEFAULT NULL,
   p_ldap_conn      	IN   DBMS_LDAP.SESSION DEFAULT NULL,
   p_user_id        	IN   NUMBER DEFAULT NULL,
   p_user_doc_id    	IN   NUMBER DEFAULT NULL,
   p_org_doc_id     	IN   NUMBER DEFAULT NULL,
   p_changetype        IN   VARCHAR2,
)

Synchronizing groups

This chapter describes the options that control what happens when the LDAP changelog contain a group object. The options include

• Map all LDAP groups to iKnowBase groups
• Map only selected LDAP groups to iKnowBase groups

Decide which groups to map

On tab one, the checkbox “sync all groups” define what happens during sync:

• When the box is checked, all groups from the LDAP-source are automatically synchronized with the corresponding iKnowBase group
• When the box is not checked, only groups that already exist in iKnowBase will be synchronized. The relationship between the two objects are controlled by the external_key of the group, which will be of the form “IKB_OID_SYNC:IKB_ADMINISTRATORS” for a group named "IKB_ADMINISTRATORS"

Hierarchical groups

The LDAP user directory typically supports groups inside groups, to easily model hierarchical relationships. iKnowBase does not support the same relationships, and hence will need to flatten the groups.

For example, in LDAP, the group “all” may contain the groups “sales” and “service”, which in turn contain all the users. This group “all” in iKnowBase will then contain all the users directly. The functionality will be the same; in fact, the flattened structure will be faster than using a hierarchical lookup.

Scheduling a Synchronization

Synchronization can run in a batch or a command line utility (such as Sql*Plus). Two methods use the same procedure to run the synchronization.

The procedure has the following signature:

oid_sync.synchronize_users ( 
p_sync_id    IN NUMBER,
p_dn         IN VARCHAR2 DEFAULT NULL,
p_changetype IN VARCHAR2 DEFAULT NULL,
p_bootstrap  IN BOOLEAN DEFAULT NULL,
p_debug IN BOOLEAN DEFAULT FALSE,
p_dbmsoutput_debug IN BOOLEAN DEFAULT FALSE);

This is the main procedure and the gate to start the synchronization. With only the mandatory parameters supplied, the synchronization uses the LDAP changelog to find which objects must be synchronized.

LDAP provider specific requirements – OpenDJ

Incremental user synchronization requires access to changeLog entries. A default installation of a single (i.e. standalone) OpenDJ directory server will not enable the “External Change Log”. (A replicated setup with more than one server will enable “External Change Log”.) See OpenDJ documentation for details regarding enabling the “External Change Log”.

Tips

• http://ludopoitou.com/2011/05/11/opendj-enabling-the-external-change-log-on-a-single-server/
• https://onemoretech.wordpress.com/2012/05/03/enabling-changelog-on-a-standalone-opendj-server/