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.
Import only. The system currently supports importing LDAP information. Exporting users and groups from the system to LDAP is not provided.
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.
XML Application Integration. The topics in this section are technical, and we assume that you are familiar with XML Application Integration (XAI).
Contents
Setting Up Your System For 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
Processing LDAP Import Requests
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.
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).
No Second Order Import. If a user is imported because it belongs to an imported group, the adapter does not import all the other groups to which the user belongs. If a group is imported because the imported user belongs to it, the adapter does not import all the other users that belong to the group.
Long User and Group Names. Users and groups whose names exceed the length limit in the system are not synchronized.
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
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.
JNDI Server Initial Context Factory. The JNDI server should have its Initial Context Factory field set to com.sun.jndi.ldap.LdapCtxFactory. This uses Sun’s LDAP JNDI provider, which is provided with the application, to access the LDAP store. If desired, you can use another JNDI LDAP provider (by setting a different initial context factory and adding the classes of that provider to the classpath).
Refer to Designing XAI JNDI Servers for more information.
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
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 |
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. |
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 |
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="(&(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="(&(objectClass=group)(name=%searchParm%))">
<LDAPCDXAttrMappings>
<LDAPCDXAttrMapping ldapAttr="name" cdxName="UserGroup" />
<LDAPCDXAttrMapping ldapAttr="description" cdxName="Description" default="Unknown" />
</LDAPCDXAttrMappings>
<LDAPEntryLinks>
<LDAPEntryLink linkedToLDAPEntity="User" linkingSearchFilter="(&(objectClass=user)(memberOf=%distinguishedName%))" linkingSearchScope="onelevel" />
</LDAPEntryLinks>
</LDAPEntry>
</LDAPEntries>
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.
Update Both Parameter Information Files. Make sure that you include the same update in both parameter information files (XAIParameterInfo.xml and MPLParameterInfo.xml).
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.
For more information about the XML Parameter Information file, refer to XAI Installation.
Open Admin Menu, LDAP Import to import users and groups into the system.
LDAP Import Setup. Your system must be appropriately configured for this page to operate correctly. Refer to Setting Up Your System For LDAP Import for more information.
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.
Username and password. Contact your LDAP system administrator for the format of the username and password to use.
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.
For more information, refer to How Does LDAP Import Work?