LDAP User Registry3.0
This feature enables support for using an LDAP server as a user registry. Any server that supports LDAP Version 3.0 may be used. Multiple LDAP registries can be configured, and then federated to achieve a single logical registry view.
Enabling this feature
To enable the LDAP User Registry 3.0 feature, add the following element declaration into your server.xml file, inside the featureManager element:
<feature>ldapRegistry-3.0</feature>
Examples
Simple LDAP registry configuration
To configure an LDAP registry, you must specify the base distinguished name, host, LDAP type, port number, and realm attributes.
Most LDAP servers require bind credentials to authenticate a client to the server.
Bind distinguished name and password are specified in the ladpRegistry element.
The following example shows a simple configuration that uses the IBM Tivoli Directory Server as an LDAP registry:
<ldapRegistry baseDN="o=acme.com" host="ldap.acme.com"
ldapType="IBM Tivoli Directory Server" port="389" realm="AcmeLdap"
bindDN="cn=testuser,o=acme.com" bindPassword="mypassword"/>Search filters
If you need to configure search behavior to include custom classes or attributes, you can customize the group and user filters, which are used for searches.
The configuration for specifying filters varies depending on the LDAP type you specify. Each available LDAP type has a different set of filter properties.
For more information, see the configuration element for the LDAP type that you want to specify.
Use the %v variable for attribute value assertions that are to be replaced by a particular login name or group name at run time.
The following example shows custom and group filters that are specified for the IBM Tivoli Directory Server LDAP type:
<ldapRegistry baseDN="o=acme.com" host="ldap.acme.com"
ldapType="IBM Tivoli Directory Server" port="389" realm="AcmeLdap"
bindDN="cn=testuser,o=acme.com" bindPassword="mypassword">
<idsFilters
groupFilter="(&(cn=%v)(objectclass=groupofnames))"
userFilter="(&(objectclass=inetorgperson)(|(uid=%v)(mail=%v)))" />
</ldapRegistry>LDAPS
To enable a secure connection to the LDAP server for encrypted communication via TLS or SSL protocols, configure the ldapRegistry element to enable Lightweight Directory Access Protocol Over Secure Socket Links (LDAPS).
Set the sslEnabled attribute to true and the sslRef attribute to your ssl id value. To enable a secure TLS or SSL connection, you must configure these connections in the ssl element.
The following example shows both the ldapRegistry element and the ssl element that the LDAP connection references.
In the ssl element, the id parameter identifies the configuration so that it can be referenced by the sslRef parameter of the ldapRegistry element.
The keyStoreRef and trustStoreRef parameters establish the data sources that are used in the TLS or SSL handshake, which enables a secure connection.
For more information about TLS and SSL connections, see SSL Repertoire.
<ldapRegistry baseDN="o=acme.com" host="ldap.acme.com"
ldapType="IBM Tivoli Directory Server" port="636" realm="AcmeLdap"
bindDN="cn=testuser,o=acme.com" bindPassword="mypassword"
sslEnabled="true" sslRef="LDAPSSLSettings" >
</ldapRegistry>
<ssl id="LDAPSSLSettings" keyStoreRef="LDAPKeyStore" trustStoreRef="LDAPTrustStore" />
<keyStore id="LDAPKeyStore" location="${server.config.dir}/resources/security/key.jks" type="JKS" password="password" />
<keyStore id="LDAPTrustStore" location="${server.config.dir}resources/security/trust.jks" type="JKS" password="password" />Custom LDAP schema classes
If you need to configure support for custom or non-default object classes, you can specify an LDAP entity type.
An entity type groups different object classes as a single entity so that the server recognizes them under the same entity name.
You can also customize the search base for any entity type to improve search times for the classes it contains.
If you create custom object classes for users or groups, make sure to update your group and user filters to include the new classes.
The following example shows entity types for users and groups, with custom search bases. The user and group filters include the custom object classes. Although this example shows configuration for the IBM Tivoli Directory Server LDAP type, all LDAP types support the userFilter and groupFilter attributes.
<ldapRegistry baseDN="o=acme.com" host="ldap.acme.com"
ldapType="IBM Tivoli Directory Server" port="389" realm="AcmeLdap"
bindDN="cn=testuser,o=acme.com" bindPassword="mypassword">
<ldapEntityType name="PersonAccount">
<objectClass>inetorgperson</objectClass>
<objectClass>customuser</objectClass>
<searchBase>ou=users,o=acme.com</searchBase>
</ldapEntityType>
<ldapEntityType name="Group">
<objectClass>groupofnames</objectClass>
<objectClass>customgroup</objectClass>
<searchBase>ou=groups,o=acme.com</searchBase>
</ldapEntityType>
<idsFilters
groupFilter="(&(cn=%v)(|(objectclass=groupofnames)(objectclass=customgroup)))"
userFilter="(&(|(objectclass=inetorgperson)(objectclass=customuser))(|(uid=%v)(mail=%v)))" />
</ldapRegistry>Federation of LDAP registries
LDAP registries are federated by default.
If you configure more than one LDAP registry in your server.xml file, then the registries are automatically federated into a common registry.
You can adjust the configuration by enabling the Federated User Registry feature and configuring the federatedRepository element. If you configure the LDAP User Registry feature version 3.0 or later, the Federated User Registry feature is enabled by default.
You can also federate LDAP registries with basic or custom user registries. The following example shows a basic registry that is federated with an LDAP registry, with configuration specified in the federatedRepository element. The participating base entry for a custom or basic registry is the o organization attribute set to equal the realm name of that registry, for example "o=RealmName". The realm name for a user registry is the value that is returned from the getRealm() method of that registry. For an LDAP registry, the realm name is the base distinguished name (baseDN) from the registry configuration. For more information, see User Registry Federation.
<server description="Federation">
<featureManager>
<feature>appSecurity-3.0</feature>
<feature>ldapRegistry-3.0</feature>
</featureManager>
<basicRegistry id="basic" realm="SampleBasicRealm">
<user name="admin" password="password" />
<user name="user1" password="password" />
<user name="user2" password="password" />
<group name="memberlessGroup" />
<group name="adminGroup">
<member name="admin"/>
</group>
<group name="users">
<member name="user1"/>
<member name="user2"/>
</group>
</basicRegistry>
<ldapRegistry realm="LdapRealm" host="LDAPHOST1.ibm.com" port="389"
baseDN="o=ibm,c=us"
ldapType="IBM Security Directory Server"/>
<federatedRepository>
<primaryRealm name="FederatedRealm" allowOpIfRepoDown="true">
<participatingBaseEntry name="o=SampleBasicRealm"/>
<participatingBaseEntry name="o=ibm,c=us"/>
</primaryRealm>
</federatedRepository>
</server>
