+

Search Tips   |   Advanced Search

Configure LDAP user registries with the Liberty profile

There are several security configuration examples on WASdev.net for reference when configuring security for the applications on the Liberty profile.

  1. Start the the LDAP server.

  2. Add the appSecurity-2.0 and ldapRegistry-3.0 Liberty features to server.xml.

  3. Optional: To communicate with an SSL-enabled LDAP server, add the ssl-1.0 Liberty feature in server.xml.

  4. Optional: Copy the truststore to the server configuration directory. For example, we can use the ${server.config.dir} variable.

    For SSL communication with an LDAP server to succeed, the Signer certificate for the LDAP server must be added to the truststore referenced by the sslAlias attribute of the <ldapRegistry> element. In the following examples, the Signer certificate must be added to the LdapSSLTrustStore.jks.

  5. Configure the LDAP entry for the server.

    If we do not want SSL for the LDAP server, remove all SSL and keystore-related lines from the following examples.

    You configure the LDAP server in server.xml or using the WebSphere Application Server Developer Tools for Eclipse. There are several security configuration examples on the WASdev.net website for reference when configuring security for the applications on the Liberty profile.

    If we use the WebSphere Application Server Developer Tools for Eclipse, the bindPassword password is encoded for you automatically. If you edit server.xml directly, we can use the securityUtility encode command to encode the bindPassword password for you. The securityUtility command-line tool is available in the $INSTALL_ROOT/bin directory. When we run the securityUtility encode command, you either supply the password to encode as an input from the command line or, if no arguments are specified, the tool prompts you for the password. The tool then outputs the encoded value. Copy the value output by the tool, and use that value for the bindPassword password.

  6. Optional: Configure certificate filter mode for the LDAP server. 
    <ldapRegistry id="LDAP" realm="SampleLdapIDSRealm" 
      host="myldap.ibm.com" port="389" ignoreCase="true" 
      baseDN="o=ibm,c=us" 
      ldapType="IBM Tivoli Directory Server" searchTimeout="8m"
      certificateMapMode="CERTIFICATE_FILTER" 
      certificateFilter="uid=${SubjectCN}"> 
      <idsFilters
      userFilter="(&amp;(uid=%v)(objectclass=ePerson))" 
      groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)
          (objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))" 
      userIdMap="*:uid" 
      groupIdMap="*:cn" 
      groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;
          groupOfNames:member;groupOfUniqueNames:uniqueMember">
      </idsFilters>
</ldapRegistry>
    For more information about certificate map mode in the Liberty profile, see LDAP certificate map mode.

  7. Optional:

    We can define mapping between LDAP attributes and the user registry <externalId> attribute.

    We can define mapping between LDAP attributes and the user registry <externalId> attribute. After the mapping is configured, when we use the user registry <externalId> attribute for any operation, the value will be equivalent to the value of the LDAP attribute that is mapped. The following example code shows the mapping defined for the user registry <externalId> attribute with the LDAP <distinguishedName> attribute for the entity type <PersonAccount>. The <autoGenerate> attribute is optional, and the value is false by default. 

    <ldapRegistry id="LDAP" realm="SampleLdapIDSRealm" 
      host="myldap.ibm.com" port="389" ignoreCase="true" 
      baseDN="o=ibm,c=us" 
      ldapType="IBM Tivoli Directory Server" searchTimeout="8m">
      <attributeConfiguration>
             <externalIdAttribute name="distinguishedName" entityType="PersonAccount" autoGenerate="false"></externalIdAttribute>
      </attributeConfiguration>
</ldapRegistry>

  8. Optional: Configure failover for multiple LDAP servers. 
    <ldapRegistry id="LDAP" realm="SampleLdapIDSRealm"
     host="ldapserver1.mycity.mycompany.com" port="389" ignoreCase="true"
      baseDN="o=ibm,c=us" ldapType="IBM Tivoli Directory Server" idsFilters="ibm_dir_server">
 <failoverServers name="failoverLdapServersGroup1">
  <server host="ldapserver2.mycity.mycompany.com" port="389" />
  <server host="ldapserver3.mycity.mycompany.com" port="389" />
 </failoverServers>
 <failoverServers name="failoverLdapServersGroup2">
  <server host="ldapserver4.mycity.mycompany.com" port="389" />
 </failoverServers>
</ldapRegistry>

<idsLdapFilterProperties id="ibm_dir_server"
     userFilter="(&amp;(uid=%v)(objectclass=ePerson))"
     groupFilter="(&amp;(cn=%v)(|(objectclass=groupOfNames)
                 (objectclass=groupOfUniqueNames)(objectclass=groupOfURLs)))"
     userIdMap="*:uid" groupIdMap="*:cn"
     groupMemberIdMap="ibm-allGroups:member;ibm-allGroups:uniqueMember;
                      groupOfNames:member;groupOfUniqueNames:uniqueMember">
</idsLdapFilterProperties>

    For more information about the ldapRegistry and failoverServers elements, see Configuration elements in server.xml.

  9. Optional: Configure multiple LDAP registries. If multiple LDAP registries are configured in server.xml, they are federated automatically. Ensure that the users are unique across all federated repositories, otherwise the user registry operations will not be successful.

    When we use multiple federated LDAP repositories, each repository must define a unique baseDN. 

    <ldapRegistry host="ldapserver1.mycity1.mycompany.com" baseDN="o=mycompany,c=us"
    port="123" ldapType="IBM Tivoli Directory Server"> 
</ldapRegistry>

<ldapRegistry host="ldapserver2.mycity2.mycompany.com" 
    baseDN="cn=users,dc=secfvt2,dc=mycity2,dc=mycompany,dc=com" 
    port="456"
    ldapType="Microsoft Active Directory" 
    bindDN="cn=testuser,cn=users,dc=secfvt2,dc=mycity2,dc=mycompany,dc=com" 
    bindPassword="{xor}KzosKyosOi0vKDs=">
</ldapRegistry>

    • Specify the federatedRepository element is not mandatory to federate multiple LDAP registries because they are federated automatically. If the federatedRepository element is specified to configure the participatingBaseEntry and primaryRealm elements, then the user registry operations are performed only on the repositories defined in the primaryRealm element. We can define the input and output property mappings for different user registry APIs under the primaryRealm element.

    • The name attribute of the participatingBaseEntry element must be the same as the value of baseDN attribute specified in the ldapRegistry element. In the example follows, the baseDN and name attributes are configured for the LDAP registry on the host ldapserver1.mycity1.mycompany.com. The value of baseDN attribute must be the same as that of sub tree in the LDAP server and the value of name attribute must be the name of that sub tree in the federated user registry. It is optional to specify the name attribute. By default, the name attribute uses the same value as the baseDN attribute. If the name attribute is specified in the ldapRegistry element, then the name attribute in the participatingBaseEntry element must use the same value as the name attribute in the ldapRegistry element. 

    <ldapRegistry host="ldapserver1.mycity1.mycompany.com" baseDN="o=mycompany,ou=myou,c=us"
    port="123" ldapType="IBM Tivoli Directory Server" name="o=mybaseentry"> 
</ldapRegistry>

<ldapRegistry host="ldapserver2.mycity2.mycompany.com" 
    baseDN="cn=users,dc=secfvt2,dc=mycity2,dc=mycompany,dc=com" 
    port="456"
    ldapType="Microsoft Active Directory" 
    bindDN="cn=testuser,cn=users,dc=secfvt2,dc=mycity2,dc=mycompany,dc=com" 
    bindPassword="{xor}KzosKyosOi0vKDs=">
</ldapRegistry>

<federatedRepository>
  <primaryRealm name="RealmName" delimiter="@" allowOpIfRepoDown="true">
   <participatingBaseEntry name="o=mybaseentry"/>
   <participatingBaseEntry name="cn=users,dc=secfvt2,dc=mycity2,dc=mycompany,dc=com"/>
    <uniqueUserIdMapping inputProperty="uniqueName" outputProperty="uniqueName"/>
    <userSecurityNameMapping inputProperty="principalName" outputProperty="principalName"/>
           <userDisplayNameMapping inputProperty="principalName" outputProperty="principalName"/>
   <uniqueGroupIdMapping inputProperty="uniqueName" outputProperty="uniqueName"/>
           <groupSecurityNameMapping inputProperty="cn" outputProperty="cn"/>
           <groupDisplayNameMapping inputProperty="cn" outputProperty="cn"/>
         </primaryRealm>
</federatedRepository>

    For more information about the federated ldapRegistry elements, see Configuration elements in server.xml.

  10. Optional: We can configure other optional attributes for the LDAP registry, such as contextPool or ldapCache, as given in the following example: 
    <ldapRegistry id="IBMDirectoryServerLDAP"         realm="SampleLdapIDSRealm"
        host="host.domain.com" port="389" ignoreCase="true"
        baseDN="o=domain,c=us"
        bindDN="cn=testuser,o=domain,c=us"
        bindPassword="mypassword"
        ldapType="IBM Tivoli Directory Server"
        searchTimeout="8m">
    <contextPool enabled="true" initialSize="1" maxSize="0" timeout="0s" waitTime="3000ms" preferredSize="3"/>
    <ldapCache>
        <attributesCache size="4000" timeout="1200s" enabled="true" sizeLimit="2000"/>
        <searchResultsCache size="2000" timeout="600s" enabled="true" resultsSizeLimit="1000"/>
    </ldapCache>
</ldapRegistry>

    • Federated user registry uses the context pooling mechanism to improve the performance of concurrent access to an LDAP server. Context pooling works at a higher level than the connection pooling. Each context entry in the context pool corresponds to a socket connection to the LDAP server. The bind credentials used by this pool are specified when configuring the LDAP registry.

    • Federated repository uses the cache mechanism for performance enhancement. It caches information about the LDAP users and groups based on the user operations performed. For example, if you perform a search operation on the LDAP users and groups, the result of the operation is cached. We can enable the ldapCache element in server.xml as shown in the previous example.

    Troubleshooting tip: To troubleshoot any LDAP authentication issues, use the following trace specifications in bootstrap.properties:

      com.ibm.ws.security.wim.*=all:com.ibm.websphere.security.wim.*=all


Subtopics


Parent topic: Configure a user registry

Concepts:

  • Authentication
  • Standalone Lightweight Directory Access Protocol registries
  • The limits to protection through password encryption

    Tasks:

  • Tune federated LDAP repositories

    Reference:
    WASdev.net

  • securityUtility command