Apache DS is a lightweight ldap server written in Java. You can think of it as an open source competitor to open ldap, IBM Tivoli Directory Server, SunOne Directory Server etc. We will install ApacheDS, make some configuration changes and use JXplorer to view/create entries in it.

Installing Apache DS is easy, configuring it after installation is little tricky:

• First of all, download apacheds-1.0.0-win32-setup.exe from here
• Double click the exe and follow the screens. I will call the installation directory <ds_home>. For example, <ds_home> could mean C:\apacheds-1.0.0
• At the end of the installation, run the configuration, which allows you to set logging behavior and server startup properties of the directory server. I accepted all the defaults, clicked Start button to start the server and clicked OK button to close configuration wizard

• Start JXplorer, click on File > Connect and enter the following values
• Host: localhost, Port: 10389, Protocol: LDAP v3, Base DN: leave blank, Level: User + Password, User DN: 'uid=admin,ou=system' (without quotes), Password: secret
• Expand System tree, select admin user and click on Table Editor tab on the right hand panel
• Click the value column on userPassword field and a User Password Data dialog pops up
• Change the password in the dialog and click OK. Remember this password, you will need it in the future!
• Click Submit button
• Disconnect from Apache DS in JXplorer using File > Disconnect
• Stop Apache DS using Service Settings menu option in the Start menu of windows
• Change the value of java.naming.security.credentials property in <apache_ds>\conf\server.xml to the new password you entered in JXplorer (yes the password is stored as clear text in Apache DS; this will change in a future version though)
• Save the file and start Apache DS
• Use JXplorer to login with new password and make sure it works

While the discussion of ldap concepts is NOT the intent of this article, here is a quick primer so that the discussion that follows will make more sense. Information is can be organized in ldap primarily using 2 styles: geographic and domain-based. Geographic style, typically used by multinational organizations, have information organized in trees that look like c=us,o=ibm etc. where c stands for country and o stands for organization. Domain based trees contain entries that look like dc=com,dc=ibm etc. where dc stands for domain component.

Once you have decided on a style, you can put your data under the tree. For example, an organization may divide its people in organizational units (represented as ou in LDAP). In that case, you will create hierarchy of ou entries. For example, ou=HR and under ou=HR, ou=benefits, ou=recruiting. 

Start JXplorer to make more sense of the information in this paragraph. Apache DS comes with ou=system, which stores the admin user for Apache DS. This is why we logged in with uid=admin,ou=system in JXplorer. Under ou=system, there are two organizational units: ou=groups and ou=users. You would put users as in bob, mike etc. under ou=users and you would create groups as in admins, users etc. under ou=groups. 

The term Access Control refers to the configuration that allows an ldap user access to a limited view of the entire tree (admin user has access to the entire tree). By default, access control is off in Apache DS, so a user (e.g. bob) created somewhere in the tree, will be able to see all other users in the tree. The term 'see all other users' means when bob logs in, he will see other users in the tree and make changes to them even though bob is not admin. This can be prevented by configuring access control in Apache DS OR by putting bob in ou=users and bob's group in ou=groups. In Apache DS, ou=users and ou=groups have special meanings. Users and groups created under those organizational units will NOT have access to other users in the tree even if access control is off and not configured. 

Why is this discussion important to us? We are going to create a WebSphere administrator in ldap and we are going to map J2EE application roles to ldap groups in WAS admin console. This is possible ONLY IF, the WebSphere admin user is able to search and view other users in the tree. To do this without configuring access control (and hence make our lives simpler), we will create ALL users and groups outside ou=users and ou=groups. Apache DS comes with dc=example,dc=com base dn entry. We will create our users and groups under this base dn. If you want to use something other than 'example' as a domain component (e.g. dc=yourorg, dc=com), replace ALL occurrences of example by yourorg in server.xml file.

Next time, we will add organizational units, users and groups to Apache DS.