Migrate a stand-alone LDAP repository to a federated repositories LDAP repository configuration
When configuring the security for the application server, we might need to migrate a stand-alone LDAP registry to a federated repositories LDAP repository configuration.
Note the specifications of the stand-alone LDAP repository to migrate, for reference when configuring the LDAP repository in federated repositories. To access these fields, on the console, click Security > Global security, and then under User account repository, select Standalone LDAP registry or Federated repositories from the Available realm definitions field and click Configure. To access these fields in a multiple security domain environment, click Security > Global Security > Security domains > domain_name, and then, under Security Attributes, expand User Realm, and click Customize for this domain. Select the Realm type as Standalone LDAP registry or Federated repositories, and then click Configure.
Avoid trouble: If we are not familiar with how to use the LDAP attributes, especially the user filter and group filter attributes, contact the LDAP administrator for assistance in setting values for these attributes that are appropriate for the system.gotcha
The following table shows the console panels and fields of the stand-alone LDAP repository configuration and their corresponding fields in a federated repositories LDAP repository configuration for mapping.
LDAP repository configuration and a federated repositories LDAP repository configuration. This table illustrates the mapping between a stand-alone LDAP repository configuration and a federated repositories
Stand-alone LDAP repository configuration LDAP repository in a federated repositories configuration Global security > Standalone LDAP registry General properties - Primary administrative user name
Global security > Federated repositories General properties - Primary administrative user name
Global security > Standalone LDAP registry LDAP server - Type of LDAP server
Global security > Federated repositories > Manage repositories > repository_ID LDAP server - Directory Type
Global security > Standalone LDAP registry LDAP server - Host
Global security > Federated repositories > Manage repositories > repository_ID LDAP server - Primary host name
Global security > Standalone LDAP registry LDAP server - Port
Global security > Federated repositories > Manage repositories > repository_ID LDAP server - Port
Global security > Standalone LDAP registry LDAP server - Failover hosts
Global security > Federated repositories > Manage repositories > repository_ID LDAP server - Failover server used when primary is not available
Global security > Standalone LDAP registry LDAP server - Base distinguished name (DN)
Global security > Federated repositories > Repository reference (Click Add Base entry to realm) General properties - Distinguished name of a base entry that uniquely identifies this set of entries in the realm
and
General properties - Distinguished name of a base entry in this repository
Global security > Standalone LDAP registry LDAP server - Search timeout
Global security > Federated repositories > Manage repositories > repository_ID > Performance General properties - Limit search time
Global security > Standalone LDAP registry LDAP server - Custom properties
Global security > Federated repositories > Custom properties Global security > Standalone LDAP registry LDAP server - Server user identity
Global security > Federated repositories General properties - Server user identity
Global security > Standalone LDAP registry Security - Bind distinguished name (DN)
Global security > Federated repositories > Manage repositories > repository_ID Security - Bind distinguished name
Global security > Standalone LDAP registry Security - Bind password
Global security > Federated repositories > Manage repositories > repository_ID Security - Bind password
Global security > Standalone LDAP registry > Advanced LDAP user registry settings General properties - Kerberos user filter
Global security > Federated repositories > Manage repositories > repository_ID Security - LDAP attribute used for Kerberos principal name
Global security > Standalone LDAP registry > Advanced LDAP user registry settings General properties - Certificate map mode
Global security > Federated repositories > Manage repositories > repository_ID Security - Certificate mapping
Global security > Standalone LDAP registry > Advanced LDAP user registry settings General properties - Certificate filter
Global security > Federated repositories > Manage repositories > repository_ID Security - Certificate filter
The Realm name field under General Properties on the federated repositories LDAP configuration panel is not listed in the previous table because it does not have a one-to-one correspondence with a field in the stand-alone LDAP configuration panel. The host name and the port number represent the realm name for the standalone LDAP server in the WAS cell. For information on changing the realm name, see the topic Realm configuration settings.
The User Filter, Group Filter, User ID map, Group ID map, and Group member ID map fields also are not listed in the previous table as they do not have a one-to-one correspondence with fields in the federated repositories LDAP repository configuration panel. These LDAP attributes are set differently in the federated repositories LDAP repository configuration and involve multiple steps. These settings are explained in detail in the following sections and procedure.
Migrate from a stand-alone LDAP repository configuration to a federated repositories LDAP repository configuration involves migrating the configuration parameters, most of which are straight forward as shown in Table 1 in the previous section. Migrating the search filters is an important part of migrating a stand-alone LDAP repository configuration to a federated repository LDAP configuration; therefore, the concept and migration of LDAP search filters is described here in detail.
Stand-alone LDAP registry search filters follow the LDAP filter syntax, where specified the attribute on which the search is based and its value.
The user filter is used for searching the registry for users. It is used to authenticate a user using the attribute specified in the filter.
The group filter is used for searching the registry for groups. It specifies the property by which to look up groups.
Examples of commonly used LDAP user filters: In the following examples of search filters, %v is replaced with the corresponding search pattern of the user or group at run time.
(&(uid=%v)(objectclass=ePerson))
Searches for users where the uid attribute matches the specified search pattern of the ePerson object class.
(&(cn=%v)(objectclass=user))
Searches for users where the cn attribute matches the specified search pattern of the user object class.
(&(sAMAccountName=%v)(objectcategory=user))
Searches for users where the sAMAccountName attribute matches the specified search pattern of the user object category.
(&(userPrincipalName=%v)(objectcategory=user))
Searches for users where the userPrinciplalName attribute matches the specified search pattern of the user object category.
(&(mail=%v)(objectcategory=user))
Searches for users where the mail attribute matches the specified search pattern of the user object category.
(&(|(sAMAccountName=%v)(userPrincipalName=%v))(objectcategory=user))
Searches for users where the sAMAccountName or the userPrincipalName matches the specified search pattern of the user object category.
Examples of commonly used group filters:
(&cn=%v)(objectCategory=group)
Looks up groups based on their common names (cn).
(&(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))
Looks up groups based on their common names (cn) and using the object class of either groupOfNames or groupOfUniqueNames.
As shown in these examples, a stand-alone LDAP registry search filter consists of LDAP attributes and object classes, based on which the search or login is performed.
We can also specify the LDAP attributes and object classes in the LDAP adapter configuration of federated repositories, but they are configured differently and provide more flexibility. In federated repositories the user is represented as PersonAccount entity type and group as Group entity type. Each entity type can have its own RDN (Relative Distinguished Name) property (rdnProperties) and object class. For example, the default RDN property of PersonAccount is uid, and the default RDN property of Group is cn. The default object class mapping depends on the LDAP server type. For example, for Tivoli Directory Server, the object class for PersonAccount is inetOrgPerson and object class for Group is groupOfNames. PersonAccount can also have login properties. When a user logs in or a search is performed for a user in a user registry, these login properties are matched with the pattern. For example, if the login properties are uid and mail, then for the search pattern, a*, all the users who match uid=a* or mail=a* are returned.
Avoid trouble: We can specify the value of User ID Map property (userIdMap) of the stand-alone LDAP repository as the RDN property (rdnProperties) or the first login property (loginProperties) in federated repositories. Though we can set both the RDN property and the login property in federated repositories, it is sufficient if you set only the RDN property. The login property is optional and we need to set it only if the login property is different from RDN property or if there are more than one login properties. If both the RDN property and login property are set, the login property takes precedence over RDN property.gotcha
Migrating search filters involves one or more of the following steps: setting the correct login properties, mapping the attributes of the back-end repository to the federated repositories properties, setting the object class, setting the search filter by using object class or object category, and setting the member or membership attribute. This mapping and configuration for federated repositories is maintained in the wimconfig.xml file.
The stand-alone LDAP registry search filter can be split into two parts:
- User or group attributes filter
- User or group object class or object category filter
For example, in the search filter, (&(cn=%v)(objectclass=user)):
- The attribute filter is (cn=%v)
- The object class filter is (objectclass=user)
These two filters are mapped separately in a federated repositories configuration:
- The attribute filter is mapped to the RDN properties or login properties configuration for user and to RDN properties configuration for group.
- The object class filter is mapped to the entity type configuration of the LDAP adapter.
The default attribute and object class mapping is set based on the LDAP server type but additional steps might be required to migrate these two filters:
- attribute filter:
- Set either or both the RDN property and login properties (if applicable)
- Mapping the federated repository property to the LDAP attribute (if applicable)
- object class filter:
- Set the object class for entity type (if applicable)
- Set the search filter of entity type (if applicable)
Some of the steps in the following procedure include two examples. In these steps:
- Example 1 is applicable to the scenario where you are migrating the search filter (&(cn=%v)(objectclass=ePerson)) from a stand-alone IBM Tivoli Directory Server LDAP repository to a federated repositories LDAP repository with the identifier LDAPTDS.
- Example 2 is applicable to the scenario where you are migrating the search filter (&(|(sAMAccountName=%v)(userPrincipalName=%v))(objectcategory=user)) from a stand-alone Microsoft Active Directory LDAP repository to a federated repositories LDAP repository with the identifier LDAPAD. sAMAccountName and userPrincipalName attributes are not defined in federated repositories, so these attributes must be mapped to federated repository properties.
- Add the LDAP repository to migrate to the federated repositories configuration.
See Table 1 in the Before beginning section of this topic, and follow the steps described in the topic Configure a single, Lightweight Directory Access Protocol repository in a new configuration under Federated repositories. These steps include links to other procedures that you must complete such as:
- Add an external repository in federated repository.
- Configure supported entity types in federated repository.
- Configure Lightweight Directory Access Protocol in a federated repository configuration.
After completing these steps, the LDAP repository to migrate will be successfully configured in the federated repository configuration.
- Set the login properties (if applicable).
Login properties are the property names used to log on to the WAS. We can specify multiple login properties using the semicolon (;) as a delimiter. The federated repositories properties commonly used as login properties are uid, cn, sn, givenName, mail, and so on.
To set login properties on the console, follow the steps in the topic Lightweight Directory Access Protocol repository configuration settings, and apply the settings under the section, Login properties.
Example 1: In the Login properties field, enter cn.
Example 2: In the Login properties field, enter uid;cn.
Complete Step 3 to map these properties to LDAP attributes.
- Map the federated repository property to the LDAP attribute (if applicable).
If the LDAP attribute is not a federated repository property, then the login property definedd must be mapped to the LDAP attribute.
- In the console, click Security > Global security.
- Under User account repository, select Federated repositories from the Available realm definitions field and click Configure. To configure for a specific domain in a multiple security domain environment, click Security domains > domain_name. Under Security Attributes, expand User Realm, and click Customize for this domain. Select the Realm type as Federated repositories and then click Configure.
- Under Related items, click Manage repositories > repository_ID, and then, under Additional properties, click the LDAP attributes link.
- If the attribute mapping exists, first delete the existing mapping for the LDAP attribute, and then add a new mapping for the attribute. Select the checkbox next to the LDAP attribute name and click Delete.
- To add an attribute mapping, click Add, and select Supported from the drop-down menu. Enter the LDAP attribute name in the Name field, the federated repositories property name in the Property name field, and the entity type which applies the attribute mapping in the Entity types field.
Example 1: Because the federated repository property cn is implicitly mapped to the cn LDAP attribute, no additional mapping is required.
Example 2: Here the search filter includes two LDAP attributes, sAMAccountName and userPrincipalName.
- For the LDAP server type, Active Directory, the LDAP attribute sAMAccountName is mapped by default to the federated repositories property, uid, as shown in the list of attributes on LDAP attributes panel. Therefore, we do not have to execute the addIdMgrLDAPAttr command to add an attribute configuration for sAMAccountName.
- If an attribute mapping for the LDAP attribute userPrincipalName exists, then delete the existing attribute mapping before adding a new configuration.
- Select the checkbox next to userPrincalName and click Delete.
- Click Add, and select Supported from the drop-down menu.
- In the Name field, enter userPrincipalName.
- In the Property name field, enter cn.
- In the Entity types field, enter PersonAccount.
- Set the object class for an entity type (if applicable).
Avoid trouble: Before executing this step, check the current mapping . If the object class mapping is already set, skip this step.gotcha
To set the object class for an entity type on the console, follow the steps in the topic Lightweight Directory Access Protocol entity types settings, and apply the following settings under the section, Object classes:
- Specify PersonAccount as the entity type name for user filters
- Specify Group as the entity type name for group filters.
Example 1: In the Entity type field, enter PersonAccount.
In the Object classes field, enter ePerson.
Example 2: In the Entity type field, enter PersonAccount.
In the Object classes field, enter user.
- Set the search filter for the entity type (if applicable).
Federated repositories performs the search based on the object class setting. To change this default setting and use object category as the filter, follow the steps in topic Lightweight Directory Access Protocol entity types settings, and apply the settings under the section, Search Filter.
Example 1: Because the search is based on object class, no additional configuration is required.
Example 2: In the Search filter field, enter (objectcategory=user).
- To migrate group filters, you must also configure the group attribute definition settings.
The steps to configure the group attribute definition settings through the console are specified in the topic Locating user group memberships in a Lightweight Directory Access Protocol registry, under the section, LDAP Registry within a Federated Repositories Registry. We can also use the wsadmin commands addIdMgrLDAPGroupDynamicMemberAttr or addIdMgrLDAPGroupMemberAttr described in the topic IdMgrRepositoryConfig command group (AdminTask).
- Save the configuration changes
- Restart the application server.
Results
After completing these steps, the LDAP repository is configured for use within the federated repositories configuration.
Related tasks
Manually configuring an Lightweight Directory Access Protocol repository in federated repository Configure Lightweight Directory Access Protocol search filters Configure Lightweight Directory Access Protocol in federated repository Configure group attribute definition settings in federated repository
IdMgrRepositoryConfig (AdminTask) Lightweight Directory Access Protocol repository configuration settings Standalone LDAP registry settings Group attribute definition settings Realm configuration settings