1. Topics:
  2. File-based user service
  3. |
  4. NONE
  1. Modules:
  2. NONE
  3. |
  4. Command line interface tasks

LDAP user service

In addition to the default file based user service, IBM® WebSphere® sMash also provides support for using an Lightweight Directory Access Protocol (LDAP) server as a user service.

To use the LDAP UserService, you need to modify the config/zero.config configuration file. For more information about directory server configuration, see the documentation of each directory server implementation.

Sample configuration and the zero.config file

To get started with the LDAP user service, the first simple example assumes that you created the following directory: 


o=hq,dc=myco,dc=com      
      |
      + + ou=people,o=hq,dc=myco,dc=com
         |     |
         |     + uid=mdavis,ou=people,o=hq,dc=myco,dc=com
         |     |
         |     + uid=afranklin,ou=people,o=hq,dc=myco,dc=com
         |
         + ou=group,o=hq,dc=myco,dc=com
               |
               + cn=Manager,ou=group,o=hq,dc=myco,dc=com
               |
               + cn=Employee,ou=group,o=hq,dc=myco,dc=com

The following sample configuration in the zero.config file is for the preceding sample directory: 

   /config/security/userservice/registryType="ldap"
   /config/security/userservice/ldap += {
      "jndiProviderUrl" : ""ldap://localhost:10389/",
      "jndiSecurityPrincipal" : "uid=admin,ou=system",
      "jndiSecurityCredentials" : "secret"
      "ldapUserIdRdnPattern" : "uid={0}",
      "ldapUserIdBaseDn" : "ou=people,o=hq,dc=myco,dc=com",
      "ldapGroupBaseDn" : "o=hq,dc=myco,dc=com"
   }

Configuring the LDAP user service in the zero.config file

When you use an LDAP based directory as the user service, you must set /config/security/userservice/registryType to ldap. You must also configure the LDAP user service in the /config/security/userservice/ldap section of the zero.config file. You can use the configuration parameters shown in the following table to do this.

Key Value Default Value Mandatory ?
jndiProviderUrl JNDI provider URL - Mandatory
jndiSecurityAuthentication The level of authentication used by JNDI. simple Optional
jndiSecurityPrincipal Administrator's principal - Mandatory in the directory server disallowing anonymous access
jndiSecurityCredentials Administrator's credential (See Leveraging XOREncoding) - Mandatory in the directory server disallowing anonymous access
jndiInitialContextFactory Initial context factory name com.sun.jndi.ldap.LdapCtxFactory Optional
ldapSearchScope The search scope set to javax.naming.directory.SearchControls: 0(SearchControls.OBJECT_SCOPE) 1(SearchControls.ONELEVEL_SCOPE) 2(SearchControls.SUBTREE_SCOPE) 2 Optional
ldapSearchTimeLimit The search time limit, in milliseconds, set to javax.naming.directory.SearchControls. 30000 Optional
ldapUserIdRdnPattern The pattern of user entries' RDN. A user ID is embedded in the place holder "{0}" . - Mandatory if the search mode is fixed; must be commented out if the mode is flex. Combined with ldapUserIdBaseDN to generate the user entries' DN.
ldapUserIdSearchFilterPattern The pattern of the user search filter. A user ID is embedded in the place holder "{0}" . (&(uid={0}) (objectclass=inetOrgPerson)) Optional (Mandatory if the search mode is flex and you need another pattern different from the default)
ldapUserIdBaseDn The root from which the LDAP user service starts to search a user. - Mandatory
ldapGroupAttributeType The attribute type of the group name. cn Optional
ldapGroupBaseDn The base DN of groups. - Mandatory
ldapGroupSearchFilterPattern The filter to search groups to which a user ID belongs. A user ID is embedded in the place holder "{0}" . (&(uniqueMember={0}) (objectclass=groupOfUniqueNames)) Optional
ignoreBaseDN Boolean flag supports fully qualified domain name (FQDN) lookups. If false, FQDN lookups will be disabled. true Optional
fullBaseDNFilterPattern The filter to search for a user based upon the fully qualified domain name. (objectclass=*) Optional
ldapSocketFactory The classname (in String format) for a custom socket factory implementation used by the LDAP service provider. - Optional

The LDAP user service implicitly uses simple as java.naming.security.authentication. No configuration is required but only the simple option is supported. When you specify the attribute type for a user ID, you must set appropriate values for ldapUserIdBaseDn, and ldapUserIdDnPattern or ldapUserIdSearchFilterPattern . When you specify the LDAP object class and its configuration for groups, you must set appropriate values for ldapGroupAttributeType, ldapGroupBaseDn, and ldapGroupSearchFilterPattern. There are two ways to perform a user search, the fixed mode and the flex mode:

Fixed mode
Searches a user with its complete DN that is produced by the ldapUserIdDnPattern value and a user ID. In this type of search ldapUserIdDnPattern and ldapUserIdBaseDn must be configured.
Flex mode
Searches a user with a search filter. It starts the search from a base directory and moves to the sub directories. In this type of search:
  • ldapUserIdBaseDn must be configured. And also ldapUserIdSearchFilterPattern must be configured if the search filter pattern defined in ldapUserIdRdnPattern is different from the default.
  • ldapSearchScope must be the default value, 2 (SearchControls.SUBTREE_SCOPE).
  • Remove or comment out ldapUserIdRdnPattern in the zero.config file. (If this is not removed from the zero.config file, then the LDAP user service searches a user in fixed mode.)

Advanced sample configurations

For an advanced setup of the LDAP user service, these examples assume that you created the following directory: 

o=hq,dc=myco,dc=com      
      |
      + + ou=people,o=hq,dc=myco,dc=com
         |     |
         |     + uid=mdavis,ou=people,o=hq,dc=myco,dc=com
         |     |
         |     + uid=afranklin,ou=people,o=hq,dc=myco,dc=com
         |
         + ou=group,o=hq,dc=myco,dc=com
         |     |
         |     + cn=Manager,ou=group,o=hq,dc=myco,dc=com
         |     |
         |     + cn=Employee,ou=group,o=hq,dc=myco,dc=com
         |
         + o=us,o=hq,dc=myco,dc=com
               |
               + ou=people,o=us,o=hq,dc=myco,dc=com
               |     |
               |     + uid=rjohnson,ou=people,o=us,o=hq,dc=myco,dc=com
               |     |
               |     + uid=dfagen,ou=people,o=us,o=hq,dc=myco,dc=com
               |
               + ou=group,o=us,o=hq,dc=myco,dc=com
                     |
                     + cn=Contractor,ou=group,o=us,o=hq,dc=myco,dc=com

A zero.config file sample for fixed search

The following sample configuration is for a fixed search based on the same directory structure shown in the preceding Advanced sample configurations section: 

   /config/security/userservice/registryType="ldap"
   /config/security/userservice/ldap += {
      "jndiProviderUrl" : ""ldap://localhost:10389/",
      "jndiSecurityPrincipal" : "uid=admin,ou=system",
      "jndiSecurityCredentials" : "secret"
      "ldapUserIdRdnPattern" : "uid={0}",
      "ldapUserIdBaseDn" : "ou=people,o=hq,dc=myco,dc=com",
      "ldapGroupBaseDn" : "o=hq,dc=myco,dc=com"
   }
In this example, the LDAP user service:
  • Accesses the directory server using LDAP, the URL of which is ldap://localhost:10389/.
  • Searches a user in the fixed mode in which:
    • It uses the attribute type uid as the user ID because ldapUserIdRdnPattern contains a uid for the user ID.
    • It searches a user entry defined in ldapUserIdBaseDn as ou=people,o=hq,dc=myco,dc=com in the directory.
    • Only uid=mdavis,ou=people,o=hq,dc=myco,dc=com and uid=afranklin,ou=people,o=hq,dc=myco,dc=com can be found by this search.
    • uid=rjohnson,ou=people,o=us,o=hq,dc=myco,dc=com and uid=dfagen,ou=people,o=us,o=hq,dc=myco,dc=com can never be found by this search because these are on a sub tree.
  • Includes search groups in which:
    • The attribute type equals cn.
    • Users are stored with the uniqueMember attribute type.
    • Entries and sub trees are under o=hq,dc=myco,dc=com.
    • cn=Manager,ou=group,o=hq,dc=myco,dc=com, cn=Employee,ou=group,o=hq,dc=myco,dc=com and cn=Contractor,ou=group,o=us,o=hq,dc=myco,dc=com can be found by this search.

A zero.config file sample for flex search

The following sample configuration is for a flex search based on the same directory structure shown in the preceding Advanced sample configurations section: 

   /config/security/userservice/registryType="ldap"
   /config/security/userservice/ldap += {
      "jndiProviderUrl" : ""ldap://localhost:10389/",
      "jndiSecurityPrincipal" : "uid=admin,ou=system",
      "jndiSecurityCredentials" : "secret"
      "ldapUserIdBaseDn" : "o=hq,dc=myco,dc=com",
      "ldapGroupBaseDn" : "o=hq,dc=myco,dc=com"
   }
In this example, the LDAP user service:
  • Accesses the directory server using LDAP, the URL for which is ldap://localhost:10389/.
  • Searches a user in the flex mode in which:
    • It uses the attribute type uid as the user ID because the default value of ldapUserIdSearchFilterPattern includes uid as the user ID.
    • It searches a user entry under o=hq,dc=myco,dc=com and sub trees.
    • uid=mdavis,ou=people,o=hq,dc=myco,dc=com and uid=afranklin,ou=people,o=hq,dc=myco,dc=com can be found by this search.
    • uid=rjohnson,ou=people,o=us,o=hq,dc=myco,dc=com and uid=dfagen,ou=people,o=us,o=hq,dc=myco,dc=com can also be found by this search because it searches for sub trees.
  • Includes search groups in which:
    • The attribute type is cn.
    • Users are stored with the uniqueMember attribute type.
    • Entries and sub trees under o=hq,dc=myco,dc=com are included.
    • cn=Manager,ou=group,o=hq,dc=myco,dc=com, cn=Employee,ou=group,o=hq,dc=myco,dc=com and cn=Contractor,ou=group,o=us,o=hq,dc=myco,dc=com can be found by this search.

A zero.config file sample for anonymous access

Suppose that the same sample directory (shown in the Advanced sample configurations section) is in the directory server allowing anonymous access. You can have the following configuration to access the directory anonymously: 

   /config/security/userservice/registryType="ldap"
   /config/security/userservice/ldap += {
      "jndiProviderUrl" : ""ldap://localhost:10388/",
      "ldapUserIdBaseDn" : "o=hq,dc=myco,dc=com",
      "ldapGroupBaseDn" : "o=hq,dc=myco,dc=com"
   }
In this example, the LDAP user service:
  • Accesses the directory server using LDAP, the URL for which is ldap://localhost:10388/.
  • Searches a user in the flex mode in which:
    • It uses the attribute type uid as the user Id because the default value of ldapUserIdSearchFilterPattern has a uid for the user ID.
    • It searches a user entry under o=hq,dc=myco,dc=com and sub trees.
    • uid=mdavis,ou=people,o=hq,dc=myco,dc=com and uid=afranklin,ou=people,o=hq,dc=myco,dc=com can be found by this search.
    • uid=rjohnson,ou=people,o=us,o=hq,dc=myco,dc=com and uid=dfagen,ou=people,o=us,o=hq,dc=myco,dc=com can also be found by this search because it searches for sub trees.
  • Includes search groups in which:
    • The attribute type is cn.
    • Users are stored with the attribute type uniqueMember.
    • Entries and sub trees under o=hq,dc=myco,dc=com are searched.
    • cn=Manager,ou=group,o=hq,dc=myco,dc=com, cn=Employee,ou=group,o=hq,dc=myco,dc=com, and cn=Contractor,ou=group,o=us,o=hq,dc=myco,dc=com can be found by this search.
  • UserService API behavior would be:
    • Set<Principal> login(String username, String password)
      • When login() is invoked with a correct username and a correct password, authentication is successfully done. Returning set should include all principles about a user itself and groups.
      • When login() is invoked with an incorrect username or an incorrect password, authentication fails. Returning set should be empty.
    • Set<Principal> getUsers(String username)
      • Returning set should include all principles about a user itself and groups.

A zero.config sample with security authentication none

Using the same sample directory, as shown above in the Advanced sample configurations section, suppose the directory server allows anonymous access. You can have the following configuration to access the directory anonymously: 

   /config/security/userservice/registryType="ldap"
   /config/security/userservice/ldap += {
      "jndiProviderUrl" : ""ldap://localhost:10388/",
      "jndiSecurityAuthentication" : "none"
      "ldapUserIdBaseDn" : "o=hq,dc=myco,dc=com",
      "ldapGroupBaseDn" : "o=hq,dc=myco,dc=com"
   }

In this example, the LDAP user service:

  • Accesses the directory server using LDAP, the URL for which is ldap://localhost:10388/.
  • Searches a user in the flex mode in which:
    • It uses the attribute type uid as the user ID because the default value of ldapUserIdSearchFilterPattern has a uid for the user ID.
    • It searches a user entry under o=hq,dc=myco,dc=com and sub trees.
    • uid=mdavis,ou=people,o=hq,dc=myco,dc=com and uid=afranklin,ou=people,o=hq,dc=myco,dc=com can be found by this search.
    • uid=rjohnson,ou=people,o=us,o=hq,dc=myco,dc=com and uid=dfagen,ou=people,o=us,o=hq,dc=myco,dc=com can also be found by this search because it searches for sub trees.
  • Includes search groups in which:
    • The attribute type is cn.
    • Users are stored with the attribute type uniqueMember.
    • Entries and sub trees under o=hq,dc=myco,dc=com are searched.
    • cn=Manager,ou=group,o=hq,dc=myco,dc=com cn=Employee,ou=group,o=hq,dc=myco,dc=com, and cn=Contractor,ou=group,o=us,o=hq,dc=myco,dc=com can be found by this search.
  • UserService API behavior
    • Set<Principal> login(String username, String password)
      • When login() is invoked with a correct username and a correct password, authentication is successfully done. Returning set should include all principles about a user itself and groups.
      • Even when login() is invoked with a correct username and an incorrect password, authentication is successfully done because security authentication is set to none. Returning set should include all principles about a user itself and groups.
    • Set<Principal> getUsers(String username)
      • Returning set should include all principles about a user itself and groups.
Note:
  • To create, update, and delete entries on a directory, you can make use of any other LDAP tools like JXplorer or LDAPStudio, for example. The LDAP user service provides read-only functions for authentication and authorization of IBM® WebSphere® sMash.

Version 1.0.0.3.25591