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 can be used. Multiple LDAP user registries can be configured and then federated to achieve a single logical user 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
Configure an LDAP user registry
To configure an LDAP user 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.
To bind with simple authentication, the bind distinguished name and password are specified in the ldapRegistry
element.
The following example shows a simple configuration that uses the IBM Tivoli Directory Server as an LDAP user 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"/>
For information on troubleshooting LDAP, see xref:Root:troubleshooting.adoc#Troubleshooting_LDAP
Customize search filters
You can customize the group and user filters to include custom classes or attributes in searches of an LDAP user registry.
The configuration for specifying filters varies depending on the LDAP type you specify. Each LDAP type has a different set of filter properties.
For more information about the LDAP type, see Feature configuration elements.
Use the %v
variable for attribute value assertions that you want to replace at run time with a particular login name or group name.
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>
Configure a secure connection with LDAPS
To enable a secure connection to an LDAP server for encrypted communication by way of 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 configurations, 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="server1/resources/security/key.jks" type="JKS" password="password" />
<keyStore id="LDAPTrustStore" location="server1/resources/security/trust.jks" type="JKS" password="password" />
Specify custom LDAP object classes
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, 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:
<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>
The user and group filters include the custom object classes. Although this example shows the configuration for the IBM Tivoli Directory Server LDAP type, all LDAP types support the userFilter
and groupFilter
attributes.
Federate LDAP user registries
LDAP user registries are federated by default.
If you configure more than one LDAP user registry in your server.xml
file, then the user registries are automatically federated into a common user registry.
You can adjust the configuration when the the Federated User Registry feature is enabled and the federatedRepository
element is configured. If you enable the LDAP User Registry feature version 3.0 or later, the Federated User Registry feature is enabled by default. Otherwise, you must manually enable the Federated User Registry feature and configure the federatedRepository
element.
You can also federate LDAP user registries with basic or custom user registries. The following example shows a basic user registry that is federated with an LDAP user registry, with the configuration specified in the federatedRepository
element:
<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>
The participating base entry for a user registry is defined by the participatingBaseEntry
element. The participating base entry value for a custom or basic user registry is the o
organization attribute set to equal the realm name of that user registry. For an LDAP user registry, the realm name is the base distinguished name from the LDAP user registry configuration.
To verify that a user is unique in the common user registry, every search request searches all federated user registries. By default, all federated user registries must return successfully or the request fails. To avoid failures if any user registry is unavailable, set the allowOpIfRepoDown
attribute on the primaryRealm
subelement to true
, as shown in the previous example.
For more information, see User Registry Federation.
Configure Kerberos authentication for LDAP servers
To configure Kerberos bind authentication for LDAP servers, you must configure the bind authentication mechanism and the Kerberos principal on the ldapRegistry
element, as shown in the following example:
<ldapRegistry id="LDAP" realm="SampleLdapADRealm" host="ldap_hostname" port="389" ignoreCase="true" baseDN="DC=example,DC=com" bindAuthMechanism="GSSAPI" krb5Principal="[email protected]" krb5TicketCache="${server.config.dir}/security/krb5-user1.cc" ldapType="Custom" />
The Kerberos principal is specified by the required krb5Principal
attribute.
You must set the bindAuthMechanism
attribute to the GSSAPI
value. This bind authentication mechanism is an alternative to the simple bind authentication mechanism, which uses a bind distinguished name and a bind password.
The krb5TicketCache
attribute is optional and specifies the location of a ccache
file, which is a credential cache file. The credentials in a ccache
file can expire. When the krb5TicketCache
attribute is specified and the principal is authenticated, the Kerberos service automatically attempts to renew the credentials before they expire.
Alternatively, you can specify the kerberos
element in your server.xml file to configure Kerberos authentication for all features that use Kerberos credentials. This element configures a keytab
file and a configuration file that can provide values to any Open Liberty features that use Kerberos credentials. The kerberos
element is optional. For more information, see Kerberos authentication for Open Liberty.
If the krb5TicketCache
attribute is not specified, Open Liberty resolves credential values from the Kerberos keytab
file that is configured in the kerberos
element. If no keytab
file or krb5TicketCache
attribute is configured, Open Liberty resolves credential values from the credential cache location that is specified by the Java SDK default settings. If both the krb5TicketCache
attribute and the keytab
attribute from the kerberos
element are configured, both files are searched for credentials. Open Liberty searches first in the ccache
file that is defined by the krb5TicketCache
attribute and then in the keytab
file that is defined by the kerberos
element.
The krb5TicketCache
attribute can be optionally specified for any feature that uses Kerberos credentials. If specified, this attribute takes precedence over any keytab
and configFile
values, Java SDK defaults, or operating system defaults. You might specify this attribute to configure credentials for a specific feature that are different from the configured values in the kerberos
element.
To determine the causes of common problems and error messages that are associated with Kerberos authentication to LDAP servers, see Troubleshooting Kerberos authentication to LDAP servers.