Prior to use LDAP utils you might need to configure the access to the server. This is done using the LDAPConfigurations object. The following example shows how to configure the access to a fictitious LDAP server with the IP 192.168.1.1. The port is the default port for LDAP access, which is 389. The port is configurable as well, check LDAPConfigurations javadoc for more information. The access is done through an account with login name 'Admin' on the group 'Users' of the domain 'myDomain.com'. The account is associated with a password 'password', which is also defined. The base search DN is also defined on the configurations. This is the top-most node from where the search is made. The base user DN refers to the base node where new users and groups are created. All the configurations can be changed programatically during program execution flow.
...
// Create an LDAP Utils object
ILDAPUtils ldapADImpl = new LDAPUtilsActiveDirectoryImpl();
// Set the configurations
ldapADImpl.getConfigurations().setHostName("192.168.1.1");
ldapADImpl.getConfigurations().setBaseUserDN("CN=Users,DC=myDomain,DC=com");
ldapADImpl.getConfigurations().setBaseSearchDN("DC=myDomain,DC=com");
ldapADImpl.getConfigurations().setUserDN("CN=Admin,CN=Users,DC=myDomain,DC=com");
ldapADImpl.getConfigurations().setPassword("password");
...
User operations include user addition, removal, update and search among others. This example will show how to add a user, verify it's existence, update some data, retrieve data from user, verify it's identity and remove it. The snippets will be presented independently for a clear presentation.
| Note: In order to be able to perform this operations you must have the server's digital certificate installed on your JVM. Check this page if you need instructions on how to do it. |
This code snippet shows how to create a new user and how to add it to the LDAP server.
...
// Create and set up the user for addition
LDAPUser user = new LDAPUser();
user.setLoginName("user");
user.setDisplayName("User Name");
user.setPassword("myPass");
user.setParentGroup("Users");
user.setEmail("user@myDomain.com");
user.setGivenName("User");
user.setUserName("User");
// Add user
ldapADImpl.addUser(user);
...
This snippet shows how to query the LDAP server to check if the user exists.
...
if(ldapADImpl.userExists("user"))
System.out.println("'user' exists on the LDAP server...");
else
System.out.println("'user' does NOT exists on the LDAP server!!");
...
The following code shows how to update an user's record. Note that the "old" login name must be passed to the updateUser() method. This must be done to ensure the user data can be still be changed if the login name is modified.
...
user.setLoginName("changed_login");
user.setDisplayName("Changed Name");
user.setPassword("changedPass");
user.setParentGroup("Changed_Group");
user.setEmail("changed.mail@myDomain.com");
user.setGivenName("Changed My Given Name");
ldapADImpl.updateUser(user, "user");
...
The following snippet shows how to verify a user's credentials.
...
String suppliedPassword = ...; // Get password from wherever you need
String suppliedLoginName = ...; // Get login name from wherever you need
if(ldapADImpl.isIdentityValid(suppliedLoginName, suppliedPassword))
System.out.println("User has valid credentials...");
else
System.out.println("User has INVALID credentials...");
...
The following snippet shows how to fetch data for a given user. The method findUserByLogin(String) returns the user with the given login name.
...
LDAPUser anotherUser = ldapADImpl.findUserByLogin("changed_login");
...
| Note: In order to be able to perform this operations you must have the server's digital certificate installed on your JVM. Check this page if you need instructions on how to do it. |
This code snippet shows how to remove an existing user from the LDAP server.
...
ldapADImpl.removeUser("changed_login");
...
Group operations include group addition, removal, update and search among others. This example will show how to add a group, verify it's existence, update some data, retrieve data from the group and remove it. The snippets will be presented independently for a clear presentation.
| Note: In order to be able to perform this operations you must have the server's digital certificate installed on your JVM. Check this page if you need instructions on how to do it. |
This code snippet shows how to create a new group and how to add it to the LDAP server.
...
// Create and set up the group for addition
LDAPGroup group = new LDAPGroup();
group.setCommonName("New Group");
group.setParentGroup("Users");
group.setName("New_Group");
group.setDescription("A new group");
// Add the group to the server
ldapADImpl.addGroup(group);
...
This snippet shows how to query the LDAP server to check if the group exists.
...
if(ldapADImpl.groupExists("New_Group"))
System.out.println("'New Group' exists on the LDAP server...");
else
System.out.println("'New_Group' does NOT exists on the LDAP server!!");
...
The following code shows how to update an group's record. Note that the "old" group name must be passed to the updateGroup() method. This must be done to ensure the group data can be still be changed if the name is modified.
...
group.setParentGroup("Changed_Group");
group.setDescription("Changed description");
ldapADImpl.updateGroup(group, "New_Group");
...
The following snippet shows how to fetch data for a given group. The method findUserByCommonName(String) returns the group with the given name.
...
LDAPGroup anotherGroup = ldapADImpl.findGroupByCommonName("New_Group");
...
| Note: In order to be able to perform this operations you must have the server's digital certificate installed on your JVM. Check this page if you need instructions on how to do it. |
This code snippet shows how to remove an existing group from the LDAP server.
...
ldapADImpl.removeGroup("New_Group");
...
This section's example assumes the following code was executed before:
...
LDAPUser user = new LDAPUser();
user.setLoginName("user");
user.setDisplayName("User Name");
user.setPassword("myPass");
user.setParentGroup("Users");
user.setEmail("user@myDomain.com");
user.setGivenName("User");
user.setUserName("User");
LDAPGroup group = new LDAPGroup();
group.setCommonName("New Group");
group.setParentGroup("Users");
group.setName("New_Group");
group.setDescription("A new group");
ldapADImpl.addUser(user);
ldapADImpl.addGroup(group);
...
Here's the code to add a user to a group.
... ldapADImpl.addUserToGroup(group.getCommonName(), user.getLoginName()); ...
To check if a user belongs to a group use the following code:
... ldapADImpl.isUserInGroup(group.getCommonName(), user.getLoginName()); ...
To get a list with all users in a group use the following code.
... Map<String, LDAPUser> usersInGroup = ldapADImpl.findUsersInGroup(group.getCommonName()); ...
The return of the findUsersInGroup() method is a map with the user's login name as key and the LDAPUser object as value.
Removing a user from a group is a matter of calling a method as follows:
... ldapADImpl.removeUserFromGroup(group.getCommonName(), user.getLoginName()); ...
LDAP Utils offers a lower-level API that allows direct LDAP attribute manipulation. There are methods to access and modify either user or group attributes. All the examples will be given with the user attributes. The same code can be applied to group attributes, providing the loginName parameter is replaced by the group's common name and the "User" part on the method's name is also replaced by "Group".
This section's example assumes the following code was executed before:
...
LDAPUser user = new LDAPUser();
user.setLoginName("user");
user.setDisplayName("User Name");
user.setPassword("myPass");
user.setParentGroup("Users");
user.setEmail("user@myDomain.com");
user.setGivenName("User");
user.setUserName("User");
LDAPGroup group = new LDAPGroup();
group.setCommonName("New Group");
group.setParentGroup("Users");
group.setName("New_Group");
group.setDescription("A new group");
ldapADImpl.addUser(user);
ldapADImpl.addGroup(group);
...
The following code adds the value "aVal" to the attribute carLicense of a user with "user" as login name.
...
ldapADImpl.addUserAttribute("user", "carLicense", "aVal");
...
The following code checks if the user with "user" as login name contains the attribute "carLicense".
...
if(ldapADImpl.userContainsAttribute("carLicense", "user"))
System.out.println("User contains the 'carLicense' attribute...");
else
System.out.println("User does NOT contains the 'carLicense' attribute...");
...
The condition should yield true and the first branch should be executed.
There are two different ways to access the attributes: getting a particular attribute or getting all attributes of an entity (user or group). The following snippet shows both ways.
...
Object attributeVal = ldapADImpl.getUserAttribute("carLicense", "user");
Map<String, Object> attributes = ldapADImpl.getUserAttributes("user");
...
The getUserAttributes() method returns a map with the attribute name as key and an Object value.
The following code changes the value of the previously set carLicense attribute.
...
ldapADImpl.setUserAttribute("user", "carLicense", "anotherVal");
...
The following code snippet removes the previously added carLicense attribute.
...
ldapADImpl.removeUserAttribute("user", "carLicense");
...
And that's pretty much it, concerning the LDAP Utils usage. Check the javadoc for a more in-depth coverage.
| Note: The following operations only work for LDAP users! LDAP groups don't benefit from these feature at the present time. |
Sometimes it might be useful to store some application-related information on the LDAP server. For example, a small store might keep a record of promotion points as an LDAP attribute for it's clients. This points might be used on the application to compute a discount or for special offers. It's rather easier to store such data on an existing attribute than to extend the LDAP schema to consider such attribute. To help with those situations the LDAP utils API offers a set of methods that allow multiple key/value pairs to be stored on a single LDAP attribute. Here are the methods:
public void storeParameterOnUserAttribute(String loginName, String attributeName, String key, String value); public void removeParameterFromUserAttribute(String loginName, String attributeName, String key); public String getParameterFromUserAttribute(String loginName, String attributeName, String key);
A note on the methods names: the key/value pair was named parameter because most of the time the information data stored with method will be used as application parameters. Also, it's more easier to write storeParameterOnUserAttribute(...) than storeKeyValuePairOnUserAttribute(...). The following snippet will show how to use the previous methods on a real-world situation. Consider the small store example presented before. The LDAP server will have users of the iNetOrgPerson type (more on this here. There will be a user with login name eddie and the carLicense iNetOrgPerson attribute will be used to store an application parameter named promotionPoints. Here's the code:
...
1
2 // Get Eddie's promotion points
3 int eddiesPoints = new Integer(ldapADImpl.getParameterFromUserAttribute("eddie", "carLicense", "promotionPoints")).parseInt();
4
5 // Give an extra promotion point to Eddie!!
6 eddiesPoints++;
7
8 // Store Eddie's points back to LDAP server
9 ldapADImpl.storeParameterOnUserAttribute("eddie", "carLicense", "promotionPoints", (new Integer(eddiesPoints)).toString());
10
11 // Eddie's promotion points expired and must be removed...
12 ldapADImpl.removeParameterFromUserAttribute("eddie", "carLicense", "promotionPoints");
13
...
Prior to code execution, if Eddie had 100 promotion points, an LDAP browser tool would show something like this:
... cn : eddie carLicense : promotionPoints=100; ...
After line 9 the output would be:
... cn : eddie carLicense : promotionPoints=101; ...
After line 12 the output would be:
... cn : eddie carLicense : ...
Note that you could have another application parameter stored on carLicense, such as expireDate that kept track of the promotion points expire date. Eddie's expireDate would be 06/06/06. The LDAP browser tool would then show:
... cn : eddie carLicense : promotionPoints=100;expireDate=06/06/06; ...
Running the code above again would yield the following output after line 9:
... cn : eddie carLicense : promotionPoints=101;expireDate=06/06/06; ...
After line 12 the output would be:
... cn : eddie carLicense : expireDate=06/06/06; ...
Note that removing the promotion points does not affect the expire date. This feature behaves almost like an hash map.