When configuring the security for your application server,
you might need to migrate a stand-alone LDAP registry to a federated
repositories LDAP repository configuration.
Before you begin
Note the specifications of your stand-alone LDAP repository
that you want to migrate, for reference when configuring the LDAP
repository in federated repositories. To access these fields, on the
administrative console, click Security > Global security.
Avoid trouble: If you are not familiar with how to
use the LDAP attributes, especially the user filter and group filter
attributes, contact your LDAP administrator for assistance in setting
values for these attributes that are appropriate for your system.
gotcha
The following table shows the administrative console
panels and fields of the stand-alone LDAP repository configuration
and their corresponding fields in a federated repositories LDAP repository
configuration for mapping.
Table 1. Mapping between a stand-alone
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
LDAP repository configuration.
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 – 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 Lightweight Directory Access Protocol (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 Lightweight Directory Access Protocol (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 Lightweight Directory Access Protocol (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 WebSphere Application Server cell. For information
on changing the realm name, see the topic Realm configuration settings.
Also see the limitation for changing realm name in a multiple security
domain environment in the topic, Federated repositories limitations.
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.
About this task
Migrating 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 you specify 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
by 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 by 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.
You 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: You 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 you 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 you 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:
- Setting either or both the RDN property and login properties (if
applicable) o
- Mapping the federated repository property to the LDAP attribute
(if applicable)
- object class filter:
- Setting the object class for entity type (if applicable)
- Setting 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.
Avoid trouble: Some of the steps in
this procedure cannot be completed using the administrative console.
You must use wsadmin commands to perform these steps. Make sure you
save your configuration and restart the application server whenever
you switch between the administrative console and the wsadmin command
window.
gotcha
- Add the LDAP repository that you want to migrate to the
federated repositories configuration.
See Table 1 in
the Before you begin section of this topic, and follow the steps described
in the topic Configuring 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:
- Adding an external repository in a federated repository configuration.
- Configuring supported entity types in a federated repository configuration.
- Configuring Lightweight Directory Access Protocol in a federated
repository configuration.
After you complete these steps, the LDAP repository that you
want to migrate will be successfully configured in the federated repository
configuration.
- Set the login properties (if applicable).
Login
properties are the property names that are used to log on to the WebSphere
Application Server. You can specify multiple login properties by 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 administrative 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
4 to map these properties to LDAP attributes.
- Save your configuration changes in the administration console.
In the administrative console, click
- 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 that you defined must
be mapped to the LDAP attribute.
Avoid trouble: This
step cannot be completed using the administrative console. The following
method involves using wsadmin commands.
gotcha
- Start the wsadmin scripting tool and use the following
command to connect to your application server:
wsadmin –username username –password password
- Use the addIdMgrLDAPAttr command
to map LDAP attributes to the corresponding federated repositories
properties.
If you get an error that the attribute
mapping exists, you must first use the deleteIdMgrLDAPAttr command
to delete the existing mapping for the LDAP attribute, and then execute
the addIdMgrLDAPAttr command to add a new mapping
for the attribute.
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 by the following entry in the wimconfig.xml
file. Therefore, you do not have to execute the addIdMgrLDAPAttr command
to add an attribute configuration for sAMAccountName. To see the LDAP
attributes that are mapped use the listIdMgrLDAPAttrs command.
<config:attributes name="sAMAccountName" propertyName="uid">
<config:entityTypes>PersonAccount</config:entityTypes>
</config:attributes>
- If an attribute mapping for the LDAP attribute userPrincipalName
exists, then delete the existing attribute mapping before adding a
new configuration.
$AdminTask deleteIdMgrLDAPAttr {-id LDAPAD –name userPrincipalName –entityTypes PersonAccount}
$AdminTask addIdMgrLDAPAttr {-id LDAPAD –name userPrincipalName –propertyName cn –entityTypes PersonAccount}
The
following code snippet is from the wimconfig.xml file after executing
this step:
<config:attributes name="userPrincipalName" propertyName="cn">
<config:entityTypes>PersonAccount</config:entityTypes>
</config:attributes>
- Save your configuration changes.
$AdminConfig save
- Restart the application server.
- 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 administrative 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 administrative
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.
You can also use the wsadmin commands addIdMgrLDAPGroupDynamicMemberAttr or addIdMgrLDAPGroupMemberAttr that
are described in the topic IdMgrRepositoryConfig command group
for the AdminTask object.
- Save your configuration changes
- Restart the application server.