Importing Users and Groups

If your organization uses Lightweight Directory Access Protocol (LDAP), you can import your existing LDAP users and groups into Framework.  Once imported, all user and group functions are available.  You can resynchronize your LDAP users and groups at any time.

This section describes how to set up your system to import users and groups from an LDAP store as well as how to do the import.

Contents

How Does LDAP Import Work?

Setting Up Your System For LDAP Import

LDAP Import

The LDAP import process uses a special XAI service (LDAP Import) that reads the information from the LDAP store and creates the appropriate security entries by calling standard XAI services to maintain users and groups.  The entire import process may be more appropriately called synchronize because groups, users, and the connections between them are synchronized between the LDAP store and your product.

Contents

Invoking The Import Process

Processing LDAP Import Requests

Invoking The Import Process

The staging control receiver invokes the LDAP Import service when it encounters a pending record on the XAI staging control table with a service ID of LDAPImport.  To create a pending LDAP import staging control record, you use the LDAP Import page to select the users or groups to be imported and click Synchronize.  The LDAP Import page populates all necessary request parameters when creating the staging control record.

Processing LDAP Import Requests

The LDAP import service calls the LDAP Import Adapter, which performs the following:

·         It reads the LDAP configuration information provided as XAI parameters to the request.  Parameters include the Java Name Directory Interface (JNDI) server, user and password for the LDAP server, and the transaction type (i.e., import).

·         It connects to the LDAP store using a JNDI specification.

·         For each element (user or group) in the request, the LDAP is searched by applying the search filter (specified for the element) and the searchParm (specified in the request).

·         The adapter goes through each entry found in the search and verifies whether or not there is already an entry in the system and whether a user belongs to a user group.  From this information, it automatically determines the action to be taken:

·         Add

·         Update

·         Link user to group

·         Unlink user from group (by setting the expiration date)

·         If the entry is a group, the adapter also imports all the users in LDAP that are linked to the group.  If the entry is a user, the adapter imports the groups to which the user belongs in LDAP.

·         For each imported entity, the adapter creates an appropriate XML request and adds it to the XAI upload staging table.  For example if the action is to add a user, it creates an XML request corresponding to the CDxXAIUserMaintenance service; and if the action is to add a group, it creates an XML request corresponding to the CDxXAIUserGroupMaintenance service. 

The XML upload staging receiver processes the upload records in sequential order (based on the upload staging ID).

In order to set up your system for LDAP import, you must:

·         Define a JNDI server that points to your LDAP server.

·         Create an XML file that maps LDAP objects to Framework objects.

·         Reference the LDAP mapping file in your XAI Parameter Information and MPL Parameter Information files.

The system is pre-configured for all other XAI components that are necessary for running LDAP Import, including:

·         LDAP Import Adapter XAI class

·         LDAP Import XAI adapter

·         LDAP Import XAI service

·         The necessary XML request and XML response schemas (LDAPImportRequest.xsd and LDAPImportResponse.xsd)

Contents

Defining a JNDI Server That Points to the LDAP Server

Mapping Between LDAP Objects And Base Security Objects

Including Your LDAP Import Mapping in the Parameter Information Files

Defining a JNDI Server That Points to the LDAP Server

XAI uses Java Name Directory Interface (JNDI) servers to locate resources that are needed by XAI.  To use LDAP Import, you must define a JNDI server that points to the LDAP server where the users and groups you want to import are located.

Mapping Between LDAP Objects And Base Security Objects

An LDAP store consists of multiple entries.  Each entry represents an object in the directory that is identified by a Distinguished Name (DN) and may contain one or more attributes.  In a typical LDAP store there is usually an entry for users and an entry for groups.  The connection between users and groups may be implemented in two different ways:

·         The users belonging to a group are defined in a special multiple-value attribute on the Group entry.

·         The groups to which a user belongs are defined in a special multiple-value attribute on the User entry.

The mapping between LDAP security objects and base security objects is stored in an XML document that can be processed by the XAI service.  As part of setting up your system for LDAP import, you need to define this mapping.  The base package comes with a sample mapping file that can be used when your LDAP store is a Microsoft Active Directory Server (ADS).  You can use this file as the basis for creating your own mapping file if you are using a different LDAP store (e.g., Novell Directory Server).

Attribute mappings are defined in the XML parameter information file under the LDAPImportAdapter section.  Note that the mapping itself is in an external file that is included in the XML parameter information file.

The XML structure:

·         Maps LDAP Entries to system objects

·         Maps attributes in the LDAP entry to attributes in the system object

·         Describes objects linked to the LDAP entry

Contents

Mapping an LDAP Entry to a Base Object

Mapping LDAP Entry Attributes to Base Object Attributes

Describing Linked Objects

Example XML Mapping

Mapping an LDAP Entry to a Base Object

Each LDAP entry is mapped to a base product object (User or Group) using an <LDAPEntry> element that has the following attributes:

Attribute	Description
name	The name of the LDAP entry: - Group - User
baseDN	The base distinguished name in LDAP for this entry.
cdxEntity	The name of the base product entity to which the LDAP entry is mapped: - User - UserGroup
searchFilter	An LDAP search filter that is used to locate LDAP entries.  A %searchParm% string in that filter is replaced by the value from the user or group search on the LDAP Import page.
Scope	Sets the scope of the search.  Valid values are: - onelevel (the value normally used) - subtree

Mapping LDAP Entry Attributes to Base Object Attributes

Each attribute in the LDAP entry is mapped to attributes in the base object using an <LDAPCDXAttrMappings> section under the LDAP entry.  Each <LDAPCDXAttrMapping> element has the following attributes:

Attribute	Description
ldapAttr	The name of the LDAP attribute to be mapped.
cdxName	The name of the base product attribute to be mapped. Note this is the name of the attribute in the XAI schema for the User or Group maintenance services.
javaClass	The name of a Java class to be called.  To provide more flexibility in attribute mappings, especially when there is not a simple one to one attribute mapping, you can derive the value of a base product attribute by calling a method in a Java class. The Java class gets the LDAP entry as input and implement its own logic for computing the value of the attribute. The class should implement the ICDXValueObtainer interface whose source can be found in the cm_templates directory. The class should be available to both the defaultWebApplication and the XAIApp.
idParm	When the javaClass attribute is specified, the IdParm attribute contains a parameter value that is passed to the Java class method.
format	When the javaClass attribute is specified, the format attribute contains a parameter value that is passed to the Java class method.
default	The default value that will be assigned to the CDx attribute when one of the following occurs: - The LDAP attribute contains a null or empty value - The LDAP attribute does not exist or is not specified. - The Java class method returns a null or empty value. Default values are applied only when creating a new entity and are not applied to updated entities.

Describing Linked Objects

When mapping the user entity you need to describe how the groups the user belongs to are retrieved.  When mapping the group entity you need to describe how the users contained in the group are retrieved.  The link information is required when displaying the list of objects that is affected by the import.

Linked objects are described using the <LDAPEntryLinks> section under the LDAP entry.  LDAP provides two methods to retrieve the linked objects:

·         The linked objects are stored as multiple-value attributes on the entity (e.g., users contained in a group are stored as a multiple-value attribute on the Group entity).

·         The linked objects are retrieved by applying a search filter on an LDAP entity (e.g., the groups to which a user belongs might be retrieved by applying a search filter to the Group entity).

Each <LDAPEntryLink> element has the following attributes:

Attribute	Description
linkedToLDAPEntity	The name of the linked entity (User or Group).  Use User when describing the Group entity.  Use Group when describing the User entity.
linkingLDAPAttr	The multiple-value attribute name on the LDAP entity that contains the linked entity.
linkingSearchFilter	The search filter to be applied to retrieve the list of linked objects, for example: (&(objectClass=group)(memberOf=%attr%)) The search filter may contain the string %attr% that acts as a substitution string and is replaced at run time by the value of the attribute named “attr” of the imported entity.  If the LDAP entry you are describing is a Group and the string is %name%, it is replaced by the value of the “name” attribute of the group you are importing.  If the LDAP entry you are describing is a User and the string is %dn%, it is replaced by the “dn” attribute of the User you are importing.
linkingSearchScope	Sets the scope of the search.  Valid values are: - onelevel (the value normally used) - subtree

Example XML Mapping

The following XML excerpt describes a mapping to the Microsoft ADS.  The example makes the following assumptions:

·         The base product attribute “DisplayProfileCode” is defaulted to “NORTHAM” when adding a new user.

·         The LDAP Group entry contains the list of users belonging to the group in the member attribute.

·         The groups to which a user belongs are retrieved by applying a search filter.

<LDAPEntries>

    <LDAPEntry name="User" baseDN="CN=Users,DC=splwg,DC=com" cdxEntity="user" searchFilter="(&amp;(objectClass=user)(name=%searchParm%))">

        <LDAPCDXAttrMappings>

            <LDAPCDXAttrMapping ldapAttr="name" cdxName="User" />

            <LDAPCDXAttrMapping cdxName="LanguageCode" default="ENG" />

            <LDAPCDXAttrMapping cdxName="FirstName" default="fn1" />

            <LDAPCDXAttrMapping cdxName="LastName" default="fn2" />

            <LDAPCDXAttrMapping cdxName="DisplayProfileCode" default="NORTHAM" />

            <LDAPCDXAttrMapping cdxName="ToDoEntries" default="1" />

            <LDAPCDXAttrMapping cdxName="TD_ENTRY_AGE_DAYS2" default="12" />

        </LDAPCDXAttrMappings>

        <LDAPEntryLinks>

            <LDAPEntryLink linkedToLDAPEntity="Group" linkingLDAPAttr="memberOf" />

        </LDAPEntryLinks>

    </LDAPEntry>

    <LDAPEntry name="Group" baseDN="CN=Users,DC=splwg,DC=com" cdxEntity="userGroup" searchFilter="(&amp;(objectClass=group)(name=%searchParm%))">

        <LDAPCDXAttrMappings>

            <LDAPCDXAttrMapping ldapAttr="name" cdxName="UserGroup" />

            <LDAPCDXAttrMapping ldapAttr="description" cdxName="Description" default="Unknown" />

        </LDAPCDXAttrMappings>

        <LDAPEntryLinks>

            <LDAPEntryLink linkedToLDAPEntity="User" linkingSearchFilter="(&amp;(objectClass=user)(memberOf=%distinguishedName%))" linkingSearchScope="onelevel" />

        </LDAPEntryLinks>

    </LDAPEntry>

</LDAPEntries>

 

Including Your LDAP Import Mapping in the Parameter Information Files

After you have defined your LDAP mapping in an XML file, you need to include it in the <AdHocParameters> sections of the XAI Parameter Information file (XAIParmameterInfo.xml) and the MPL Parameter Information (MPLParameterInfo.xml) file.  The definitions are made to the LDAPImport adapter under an <Adapters> section that you add. 

The following example shows an excerpt from the parameter information files:

<AdHocParameters>

    <Adapters>

        <Adapter name="LDAPImport" maxReturnedResults="300"> 

        <?XAI includeURL=file:///c:\Cdx\Product\Servers\MAIN_PROD_ORA\cisdomain\xai\ldapdef.xml ?>

        </Adapter>

    </Adapters>

</AdHocParameters>

 In the example above, the mapping file is called ldapdef.xml.

The maxReturnedResults attribute limits the number of LDAP entries the adapter returns for the search request.  This limit is only applicable to the LDAP Import user interface.  The import process itself is not affected by this parameter.

Open Admin Menu, LDAP Import to import users and groups into the system. 

Description of Page

Enter the LDAP JNDI server that should be used to connect to the LDAP server from which you want to import users or groups.  Refer to Defining a JNDI Server for more information.

If the LDAP server from which you are importing users or groups requires authentication, specify an LDAP User and LDAP Password for the server.

From the LDAP Entity drop-down list, select either User or User Group depending on whether you want to import users or groups from the LDAP server.

Select the name of the User or Group that you want to import.  (The label of this field changes depending on the LDAP Entity you selected.)  You can use the search button to search for a list of users or groups that exist in the LDAP store.

After all fields have been specified, click the Find icon to return a list of all the objects contained in the selected user or group.  If a user is specified, all the groups to which the user belongs are displayed in the grid.  If a group is specified, all the users that belong to the group are displayed in the grid.

Click the Synchronize button to import the specified user or group and its linked objects (shown in the grid).

The LDAP Import service creates the configuration parameters on the XML staging control table. You are automatically transferred to the XAI Staging Control page where you can view the status of your request.