Sunday, January 2, 2011

Spring 3 - Quartz Scheduling

In this tutorial we will explore Spring 3's task scheduling support using the Quartz Scheduler. Spring also provides scheduling support using annotations (see Spring 3 - Task Scheduling via Annotations: @Scheduled, @Async), and via XML configuration (see Spring 3 - Task Scheduling via "scheduled-tasks" Element). We will build our application on top of a simple Spring MVC 3 application. Although MVC is not required, I would like to show how easy it is to integrate.

Why do we need scheduling?
Scheduling is needed if you want to automate the repetition of a task at specific intervals or particular date. You could of course manually watch the time and execute your task, albeit an inefficient task. Who wants to watch the computer every 3 seconds just to hit the Enter key? No one.

The work
We want to run the following sample class at specific intervals:

The task that we're interested is inside the work() method. This example is based on Mark Fisher's example at Task Scheduling Simplifications in Spring 3.0. This method retrieves the thread name, prints the starting and beginning of the method, simulates work by putting the thread in sleep for 10 seconds.

To schedule this using Quartz, we'll do it in two ways via the JobDetailBean and via the MethodInvokingJobDetailFactoryBean.

MethodInvokingJobDetailFactoryBean
The MethodInvokingJobDetailFactoryBean is the simpler of the two, albeit simple options. So we'll start with that.

Using the MethodInvokingJobDetailFactoryBean
Often you just need to invoke a method on a specific object. Using the MethodInvokingJobDetailFactoryBean you can do exactly this.... Using the MethodInvokingJobDetailFactoryBean, you don't need to create one-line jobs that just invoke a method, and you only need to create the actual business object and wire up the detail object.

Source: http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/scheduling.html
Let's examine an actual example. We'll create a new class SyncWorker that implements a Worker interface.

Worker

SyncWorker

This worker is synchronous which means if we have to call this worker 10 times, it will block the other workers. They cannot start immediately until the first one is finished. If you like to see an example of asynchronous scheduling, please see Spring 3 - Task Scheduling via Annotations: @Scheduled, @Async

To run this using the MethodInvokingJobDetailFactoryBean, we need to declare it in an XML configuration:

quartz-job.xml

We have declared our SyncWorker as a simple bean:

Then we made a reference to our worker inside a MethodInvokingJobDetailFactoryBean. On the targetMethod property, we assign the method name work() that needs to be scheduled.

In order for this to be triggered, we need a Trigger.

This trigger runs every 10 seconds, with a starting delay of 10 seconds as well.
In order for this trigger to be managed, we need a Scheduler
The SchedulerFactoryBean purpose is to schedule the actual jobs assigned in the triggers. You may wonder why we need to have a scheduler, a trigger, and a job just to schedule a single task in Quartz?
Quartz uses Trigger, Job and JobDetail objects to realize scheduling of all kinds of jobs. For the basic concepts behind Quartz, have a look at http://www.opensymphony.com/quartz. For convenience purposes, Spring offers a couple of classes that simplify the usage of Quartz within Spring-based applications. Source: http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/scheduling.html
Let's run the application and see the output on the logs:
Notice how our worker is executed. It runs synchronously as expected. The numbers in Worker-1, Worker-2, and etc represents the thread ppol. Our max Worker is 10, so we have a pool size of 10. To modify this value, add the following quartzProperties in the SchedulerFactoryBean:

JobDetailBean
Let's explore another way of scheduling using Quartz. We'll use the JobDetailBean.

What is a JobDetailBean
Convenience subclass of Quartz's JobDetail class, making bean-style usage easier.

JobDetail itself is already a JavaBean but lacks sensible defaults. This class uses the Spring bean name as job name, and the Quartz default group ("DEFAULT") as job group if not specified.

Source: http://static.springsource.org/spring/docs/3.0.x/javadoc-api/org/springframework/scheduling/quartz/JobDetailBean.html
Let's examine an actual example. We'll create a custom class CustomJob that extends QuartzJobBean and implements StatefulJob

CustomJob

Notice our worker is a normal private field. We have assigned a setter method for this worker.

This is required so that Spring can inject the value from the XML configuration. Our worker is executed inside the executeInternal() method:

You can access various details of your job via the JobExecutionContext.

To activate our CustomJob, we need to enable it in the XML configuration.

quartz-job.xml

The configuration is similar with our first example using MethodInvokingJobDetailFactoryBean. The main difference here is we're using aJobDetailBean

We're also using a CronTrigger. Nonetheless, the idea is similar with our initial example.

Let's run our application and see the output:

Same result. We just have more logs because of the CustomJob.

That's it. We've added scheduling support using the Quartz Scheduler. We've used two support beans to realize our goal. Feel free to modify the MVC app to fit your needs. You might wanna try integrating a web service with scheduling and show the results via MVC. The welcome page is accesible at
http://localhost:8080/spring-mvc-quartz-scheduling/krams/main/welcome
The best way to learn further is to try the actual application.

Download the project
You can access the project site at Google's Project Hosting at http://code.google.com/p/spring-mvc-scheduling/

You can download the project as a Maven build. Look for the spring-mvc-quartz-scheduling.zip in the Download sections.

You can run the project directly using an embedded server via Maven.
For Tomcat: mvn tomcat:run
For Jetty: mvn jetty:run

If you need to know more about Task Scheduling in Spring 3.0, please visit the following links:

StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring 3 - Quartz Scheduling ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring 3 - Task Scheduling via Annotations: @Scheduled, @Async

In this tutorial we will explore Spring 3's task scheduling support using annotations. We will be using @Scheduled and @Async annotations. Spring also provides scheduling support using the Quartz Scheduler, and via XML configuration (see Spring 3 - Task Scheduling via "scheduled-tasks" Element). We will build our application on top of a simple Spring MVC 3 application. Although MVC is not required, I would like to show how easy it is to integrate.

Why do we need scheduling?
Scheduling is needed if you want to automate the repetition of a task at specific intervals or particular date. You could of course manually watch the time and execute your task, albeit an inefficient task. Who wants to watch the computer every 3 seconds just to hit the Enter key? No one.

The work
We want to run the following sample class at specific intervals:

The task that we're interested is inside the work() method. This example is based on Mark Fisher's example at Task Scheduling Simplifications in Spring 3.0. This method retrieves the thread name, prints the starting and beginning of the method, simulates work by putting the thread in sleep for 10 seconds.

To schedule this using Spring's annotation support, we'll use the @Scheduled annotation.

The @Scheduled Annotation
Spring 3.0 also adds annotation support for both task scheduling and asynchronous method execution.... The @Scheduled annotation can be added to a method along with trigger metadata.

Source: http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/scheduling.html
To enable this annotation we need to add the annotation-driven element:

You also need to add the component-scan element. We didn't enable it here since it's already added in the applicationContext.xml (see the accompanying source code at the end of this tutorial)

Let's examine an actual example. We'll create a new class SyncWorker that implements a Worker interface.

Worker

SyncWorker

This worker is synchronous which means if we have to call this worker 10 times, it will block the other workers. They cannot start immediately until the first one is finished. We didn't do anything to make this implementation synchronous. It's the default.

The class that calls this SyncWorker is a scheduler service.
Notice the @Scheduled annotation in the doSchedule() method. This tells Spring to mark this method for task scheduling. Inside the @Scheduled, there's a metadata that describes when the method should be triggered. The following metadata all have the same value (5 seconds) but they are interpreted differently:
fixedDelay=5000
fixedRate=5000 
cron="*/5 * * * * ?"
fixedDelay: An interval-based trigger where the interval is measured from the completion time of the previous task. fixedRate: An interval-based trigger where the interval is measured from the start time of the previous task. cron: A cron-based trigger Running the application gives us the following logs:
Notice how the tasks are run sequentially every 5 seconds.

What if we want to run the workers asynchronously, meaning we don't want to wait for worker 1 to finish before we start worker 2, or worker 3, and so forth? There are valid reasons like efficient use of physical resources and time.

To make a worker asychronous, we add the @Async annotation in the method that needs to be asychronous.

The @Async Annotation
The @Async annotation can be provided on a method so that invocation of that method will occur asynchronously. In other words, the caller will return immediately upon invocation and the actual execution of the method will occur in a task that has been submitted to a Spring TaskExecutor.

Source: http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/scheduling.html
To enable this annotation we use the same annotation-driven element.

Let's examine an actual example. We'll create a new class AsyncWorker that implements the Worker interface earlier.

AsyncWorker

This worker is asychronous. The caller (the scheduler service) will return immediately upon invocation.

The class that calls this AsyncWorker is the same scheduler service we had earlier. We
just need to change the value of @Qualifier

Same implementation, except for the asyncWorker reference. It's unbelievably easy.

Running the application gives us the following logs:

Notice how the tasks are run asynchronously.

One final note. Let's examine the XML file that contains the annotation-driven element:

Notice I have added two attributes in the annotation-driven element: executor and scheduler. Both are references to the beans declared at the bottom of the file. The ids of these beans become the default thread name prefixes. See below (taskScheduler-1 and executorWithPoolSizeRange-1):


That's it. We've added scheduling support using the @Scheduled annotation, and asychronous support using the @Async annotation. To see the output, please check the logs. Feel free to modify the MVC app to fit your needs. You might wanna try integrating a web service with scheduling and show the results via MVC. The welcome page is accesible at
http://localhost:8080/spring-mvc-task-scheduling-annotation/krams/main/welcome
The best way to learn further is to try the actual application.

Download the project
You can access the project site at Google's Project Hosting at http://code.google.com/p/spring-mvc-scheduling/

You can download the project as a Maven build. Look for the spring-mvc-task-scheduling-annotation.zip in the Download sections.

You can run the project directly using an embedded server via Maven.
For Tomcat: mvn tomcat:run
For Jetty: mvn jetty:run

If you need to know more about Task Scheduling in Spring 3.0, please visit the following links:

StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring 3 - Task Scheduling via Annotations: @Scheduled, @Async ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring 3 - Task Scheduling via "scheduled-tasks" Element

In this tutorial we will explore Spring 3's task scheduling support based on the scheduled-tasks element. Spring also provides scheduling support using the Quartz Scheduler. However, we will focus solely on Spring 3's built-in scheduler for this tutorial. We will build our application on top of a simple Spring MVC 3 application. Although MVC is not required, I would like to show how easy it is to integrate.

Why do we need scheduling?
Scheduling is needed if you want to automate the repetition of a task at specific intervals or particular date. You could of course manually watch the time and execute your task, albeit an inefficient task. Who wants to watch the computer every 3 seconds just to hit the Enter key? No one.

The work
We want to run the following sample class at specific intervals:

The task that we're interested is inside the work() method. This example is based on Mark Fisher's example at Task Scheduling Simplifications in Spring 3.0. This method retrieves the thread name, prints the starting and beginning of the method, simulates work by putting the thread in sleep for 10 seconds.

To schedule this using Spring's scheduling support via XML, we'll use the tag scheduled-tasks element.

The 'scheduled-tasks' element
The most powerful feature of Spring's task namespace is the support for configuring tasks to be scheduled within a Spring Application Context. This follows an approach similar to other "method-invokers" in Spring, such as that provided by the JMS namespace for configuring Message-driven POJOs. Basically a "ref" attribute can point to any Spring-managed object, and the "method" attribute provides the name of a method to be invoked on that object.

Source: Spring Framework 3 Reference, Chapter 25. Task Execution and Scheduling
We've prepared a separate XML file to contain all configurations relating to scheduling.

spring-scheduler.xml

This config is actually shorter if we remove the comments.

Notice we declared three references to our tasks inside the scheduled-tasks element:

Each has task has their own triggers (the schedule when they will be executed). These tasks are managed by the taskScheduler

The id is used as the default thread name prefix. You can also configure the pool size.

We've declared three beans as tasks:

These are simple POJOs with no dependency over Spring's scheduling. This mean we can easily add scheduling to existing beans.

Here are the classes for these beans:

FixedDelayWorker

FixedRateWorker

FixedDelayWorker

Worker

Running the application, the logs show the following output:

Notice how the FixedRateWorker is executed multiple times. This doesn't look right. We've scheduled it using the fixed-rate attribute (an interval-based trigger where the interval is measured from the start time of the previous task). This means it will run every 5 seconds from the start time of the previous task.

Starting from 06:00:31 up to 06:01:01, there are five intervals of 5 seconds each.
06:00:36
06:00:41
06:00:46
06:00:51
06:00:56
This means our FixedRateWorker has been queued 5 times. If we look at the logs from 06:01:01 to 06:01:41, FixedRateWorker has been executed 5 times. The point to take here is be careful when combining multiple schedules. We combined them here for the sake of completeness. Also, we've run the following example within a Spring MVC application just by adding an extra configuration spring-scheduler.xml

To see the output, please check the logs :) Feel free to modify the MVC app to fit your needs. You might wanna try integrating a web service with scheduling and show the results via MVC. The welcome page is accesible at
http://localhost:8080/spring-mvc-task-scheduling-xml/krams/main/welcome
The best way to learn further is to try the actual application.

Download the project
You can access the project site at Google's Project Hosting at http://code.google.com/p/spring-mvc-scheduling/

You can download the project as a Maven build. Look for the spring-mvc-task-scheduling-xml.zip in the Download sections.

You can run the project directly using an embedded server via Maven.
For Tomcat: mvn tomcat:run
For Jetty: mvn jetty:run

If you need to know more about Task Scheduling in Spring 3.0, please visit the following links:

StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring 3 - Task Scheduling via "scheduled-tasks" Element ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

Spring Security - MVC: Using an LDAP Authentication Provider

In this tutorial we will setup a simple Spring MVC 3 application, secured by Spring Security. Our users will be authenticated against an LDAP provider. We'll explore how we can configure an LDAP authentication provider. For this tutorial we will leveraged on our existing tutorials to lessen the repetition of steps. The overall structure of our application will be based on Spring Security 3 - MVC: Using a Simple User-Service Tutorial. This is a good exercise to show how easy we can change providers without disrupting the whole flow of our existing system. The LDAP server and entries will be based on LDAP - Apache Directory Studio: A Basic Tutorial

What is LDAP?
The Lightweight Directory Access Protocol (LDAP) is an application protocol for reading and editing directories over an IP network. A directory is an organized set of records. For example, the telephone directory is an alphabetical list of persons and organizations, with each record having an address and phone number. A directory information tree often follows political, geographic, or organizational boundaries. LDAP directories often use Domain Name System (DNS) names for the highest levels. Deeper inside the directory might appear entries for people, departments, teams, printers, and documents.

Source: http://en.wikipedia.org/wiki/LDAP
If this is your first time to LDAP, you might be wondering how is this different from an RDBMS. I suggest my readers to visit the following article Should I Use a Directory, a Database, or Both?

We'll start immediately with the spring-security.xml configuration.

spring-security.xml

Honestly, this is the only file that you need to change from the Spring Security 3 - MVC: Using a Simple User-Service Tutorial.

Actually, we just deleted a couple of entries. The old configuraiton contains an in-memory user-service provider:

The new configuration contains an LDAP authentication provider:

The real tricky part here is ensuring that you can connect to your LDAP server and ensuring that you've mapped correctly the attribute names from your ldap-authentication-provider to the LDAP Directory Information Tree.

To get a better understanding, let's examine the directory structure of the server. You will gain better insight if you've read first LDAP - Apache Directory Studio: A Basic Tutorial.

Here's server's structure:
mojo
 |
 |--groups
 |    |
 |    |--Admin
 |    |--User
 |
 |--users
      |
      |--guy1
      |--guy2
      |--guy3
      |--guy4
Here's a screenshot of the server's directory:

Let's focus on the elements of the ldap-authentication-provider

The attribute value of the user-search-filter="(uid={0})" corresponds to the attribute we've declared for the users
The {0} in the (uid={0}) will be replaced by the username entered in the form.

The value of the user-search-base="ou=users" corresponds to the attribute we've declared in the directory tree

The attribute value of the group-search-filter="(uniqueMember={0})" corresponds to the attribute we've declared for the groups
The {0} in the (uniqueMember={0}) represents the Distinguished Name (DN) of the user. On our sample data, the dn for Hugo Williams is cn=Hugo Williams,ou=users,o=mojo. The DN is similar with the primary key in relational databases.

The value of the group-search-base="ou=groups" corresponds to the attribute we've declared in the directory tree

The attribute value of the group-role-attribute="cn" corresponds to the attribute we've declared for the groups. Spring Security uses this value of this attribute to determine the authorization level of the user.

The value of the role-prefix="ROLE_" is used to indicate what prefix should be added on the values received from group-role-attribute="cn". If you examine carefully the server's structure, we have two roles declared as cn=Admin and cn=User
The values that will be returned are Admin and User. With role-prefix="ROLE_", they will become ROLE_ADMIN and ROLE_USER respectively.

The LDAP Server
Let's examine ldap-server tag.


The url ldap://localhost:10389/o=mojo is composed of the server's url and port number ldap://localhost:10389/ and the base parent path o=mojo

The attribute manager-dn="uid=admin,ou=system" is based on the Distinguished Name of the admin. Normally, you will be provided by your administrator with a custom access, but for this tutorial we're relying on the default values to make things simple.

That's it. We've setup a simple Spring MVC 3 application, secured by Spring Security. Our users are authenticated against an LDAP provider. We've also explored how the various attributes map to an existing directory structure. This also means we can customize our mappings and assign different attribute names.

The best way to learn further is to try the actual application.

Download the project
You can access the project site at Google's Project Hosting at http://code.google.com/p/spring-security-ldap/

You can download the project as a Maven build. Look for the spring-security-ldap.zip in the Download sections.

You can run the project directly using an embedded server via Maven.
For Tomcat: mvn tomcat:run
For Jetty: mvn jetty:run
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: Spring Security - MVC: Using an LDAP Authentication Provider ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share

LDAP - Apache Directory Studio: A Basic Tutorial

In this tutorial we will setup a basic LDAP structure containing users and roles. We will be using the excellent Apache Directory Studio IDE. This tutorial will be the basis for our other Spring LDAP integration tutorials.

What is Apache Directory Studio?
The Eclipse based LDAP browser and directory client

Apache Directory Studio is a complete directory tooling platform intended to be used with any LDAP server however it is particularly designed for use with ApacheDS. It is an Eclipse RCP application, composed of several Eclipse (OSGi) plugins, that can be easily upgraded with additional ones. These plugins can even run within Eclipse itself.

Source: http://directory.apache.org/studio/
What is LDAP?
The Lightweight Directory Access Protocol (LDAP) is an application protocol for reading and editing directories over an IP network. A directory is an organized set of records. For example, the telephone directory is an alphabetical list of persons and organizations, with each record having an address and phone number. A directory information tree often follows political, geographic, or organizational boundaries. LDAP directories often use Domain Name System (DNS) names for the highest levels. Deeper inside the directory might appear entries for people, departments, teams, printers, and documents.

Source: http://en.wikipedia.org/wiki/LDAP
If this is your first time to LDAP, you might be wondering how is this different from an RDBMS. I suggest my readers to visit the following article Should I Use a Directory, a Database, or Both?

A Brief Background
We have a small startup company named Mojo Enterprises. We have four people, and two of them are admins. Our task is to create a hierarchical structure of our organization using LDAP because we anticipate the eventual growth of the company. We may have hundreds of people from different departments in five years time. Each has their own information and structure. These information and structure will be shared among different applications of the company. LDAP is a good protocol to meet all these requirements.

Layout the Structure
Let's define the important elements of the company.

Company Name: Mojo Enterprises
Members:
  • Hugo Williams
  • John Keats
  • John Milton
  • Robert Browning
Admins:
  • Hugo Williams
  • John Keats
LDAP is a hierarchical tree structure, so our design will be influenced by that.

We need to assign the topmost parent of our structure. Logically, the name of the company fits that requirement. We'll pick the name mojo as the topmost parent.

Under the mojo we will assign our members. There are many ways to organize our members. We can organize them by gender, by job function, and etc. For this tutorial we'll organize them based on identity and roles. We'll put all the identities of each person in a separate element, while the roles will be placed on another element.

Under the roles we have two sub-divisions. Remember we have the regular users and the admins. What we'll do is divide the roles into elements.

Here's how our structure would like:
mojo
 |
 |--roles
 |    |
 |    |--admin
 |    |--regular
 |
 |--identities
      |
      |--guy1
      |--guy2
      |--guy3
      |--guy4
We'll make the names a little bit formal, and make it conform with the naming convention of LDAP. For the topmost parent, we'll retain mojo. For roles, we'll use groups instead. For identities, we'll use users

When we're done with this tutorial, we should have the following structure:
It's really simple to do. All you need is an Apache Directory Studio, this tutorial, and patience.

Install the Apache Directory Studio
Before we can do any LDAP-related work, we need to have an IDE first. Although it's not required, we'll require it for this tutorial. And why not? It's free anyway.

To install the Apache Directory Studio, visit the following link http://directory.apache.org/studio/downloads.html Follow the instructions on that link
for the installation steps.

Create a New Server
Once you have installed the studio, we need to create a server. Here are the steps:

1. Open Apache Directory Studio.

3. Go to File, and click New. A popup window will open.

4. Expand the Apache DS folder, and select the Apache DS Server

5. Click Next.

6. Type-in any name for the server. For example, apache-ds-server

7. Click Finish.

8. A new server has been added on your Servers panel.
If you can't see the Servers panel, go the menu bar then click Window > Show View > Apache DS > Servers

9. Select your server, then click the Run button.
Your server should now be running.

Create a Connection
To browse the contents of the server, we need to create a connection. Here are the steps:

1. Right-click on your server.

2. Select LDAP Browser

3. Select Create a Connection. An alert message will popup indicating the a new connection has been created.

4. Go to the Connections panel.
If you can't see the Connections panel, go the menu bar then click Window > Show View > LDAP Browser > Connections

5. Double-click the name of the new connection you've created earlier.

6. The LDAP Browser panel should refresh and show the contents of the server.
Notice the topmost entry of this server is DIT, followed by the Root DSE.

7. Expand the Root DSE folder. There are two sub-entries: ou=schema and ou=system.
These are partitions in the server. Do not modify them unless you know what you're doing.

Create a New Partition
To add our company to the root tree, we need to create a new partition. Everything related to the company will be attached to this new partition. Here are the steps:

1. Go to the Servers panel, and right-click your server.

2. Select Open Configuration. A server.xml editor will appear on the main panel.

3. At the bottom part of server.xml, there are five tabs. Click the Partitions tab.
The Partitions tab should appear.

4. Click on Add and enter the following details for this new partition.

ID: mojo
Cache Size: 100
Suffix: o=mojo

5. Save your changes (CTRL + S). A new partition has been added.

6. Restart your Apache DS server.

7. Refresh the LDAP Browser panel.

8. Click on the Root DSE folder. A new editor will open containing the details of this folder.
Notice the namingContexts attribute. The namingContexts o=mojo shows in the lists. However it doesn't show under the Root DSE tree because we need to add the organization manually in the tree.

Add the Parent Organization
Our company is an organization. In LDAP, to represent a company we use the organization object which is represented by the alias o. So if our company's name is mojo, the Distinguished Name (dn) of the company is o=mojo. It's a naming convention. (The Distinguished Name is like the primary key or primary identity).

To create the organization object, follow the steps below:
1. Right-click on the Root DSE folder. Select New. Select New Context Entry

2. Select Create entry from scratch. Click Next. The Object classes window will appear.

3. Find the organization object. Select it then click Add

4. Click Next. Now you need to enter a Distinguished Name (dn). Click on the pulldown menu. Select o=mojo.

5. Click Next. The Attributes window will appear. Examine the values.

6. Click Finish. Notice the new partition now appears under the Root DSE.

Add the Organizational Units
Earlier we mentioned we'll structure our company based on users (contains personal information of the user) and groups (contains the authorization level of each person).
Both of these represent an organizational unit.

In LDAP, to represent an organizational unit we use the organizationalUnit object which is represented by the alias ou. So if we have a unit name users, the Distinguished Name (dn) is ou=users,o=mojo. Why is there an o=mojo? It's a naming convention. The same convention applies to groups. The Distinguished Name (dn) is ou=users,o=mojo. This can be likened the way we name URLS. For example, users.mojo.com or groups.mojo.com.

We'll add first the users unit. Here are the steps:
1. Go to the LDAP Browser panel. Expand the Root DSE folder.

2. Right-click the o=mojo entry. Select New. Select New Entry.
The Entry Creation Method window will appear.

3. Select Create entry from scratch. Click Next. The Object Classes window will appear.

4. Find the organizationalUnit object. Select it then click Add.

5. Click Next. Now you need to enter a Distinguished Name (dn).
The Parent field should read o=mojo.

On the RDN field enter ou. On the value field enter users. The DN Preview should read ou=users,o=mojo

6. Click Next. The Attributes window will appear. Examine the values.

7. Click Finish. We've just created the ou=users organizational unit.

Add the Second Organizational Units
We've just added the ou=users organizational unit. We need to add the organizational unit for groups as well. We'll follow the same steps.

1. Go to the LDAP Browser panel. Expand the Root DSE folder.

2. Right-click the o=mojo entry. Select New. Select New Entry.
The Entry Creation Method window will appear.

3. Select Create entry from scratch. Click Next. The Object Classes window will appear.

4. Find the organizationalUnit object. Select it then click Add.

5. Click Next. Now you need to enter a Distinguished Name (dn).
The Parent field should read o=mojo.

On the RDN field enter ou. On the value field enter groups. The DN Preview should read ou=groups,o=mojo

6. Click Next. The Attributes window will appear. Examine the values.

7. Click Finish. We've just created the ou=groups organizational unit.

Add the Staff
Now we need to add our four people:
  • Hugo Williams
  • John Keats
  • John Milton
  • Robert Browning
Admins:
  • Hugo Williams
  • John Keats
We'll place their personal information under the ou=users; whereas we'll place their authorization levels under the ou=groups.

Let's start with the ou=users. We'll be adding four persons. We'll represent each person using the inetOrgPerson object.

What's an inetOrgPerson object?
The inetOrgPerson object class is a general purpose object class that
holds attributes about people. The attributes it holds were chosen
to accommodate information requirements found in typical Internet and
Intranet directory service deployments.
Source: http://www.faqs.org/rfcs/rfc2798.html
An inetOrgPerson can contain a user id (uid) and password (userPassword) which will be useful later for authenticating users from using LDAP.

Here are the steps we need to do:
1. Go to the LDAP Browser panel. Expand the Root DSE folder.

2. Expand the o=mojo entry.

3. Right-click the ou=users entry. Select New. Select New Entry.
The Entry Creation Method window will appear.

4. Select Create entry from scratch. Click Next. The Object Classes window will appear.

5. Find inetOrgPerson object. Select it then click Add.

6. Click Next. Now you need to enter a Distinguished Name (dn).
The Parent field should read ou=users,o=mojo.

On the RDN field enter cn. On the value field enter Hugo Williams.
The DN Preview should read cn=Hugo Williams,ou=users,o=mojo (cn represent Common Name).

7. Click Next. The Attributes window will appear. Examine the values.

8. Under the sn attribute, enter Williams (sn stands for Surname)

9. We need to add a username for this user. Right-click on the same window. Select New Attribute. The Attribute Type window will appear.

10. On the Attribute type field, enter uid. This will serve as the username of the person.

11. Click Next, then click Finish.

12. You're back on the Attributes window. On the uid attribute value, enter hwilliams


13. We need to add a password for this user. Right-click on the same window. Select New Attribute. The Attribute Type window will appear.

14. On the Attribute type field, enter userPassword. This will serve as the password of the person.

15. Click Next, then click Finish.

16. You will be asked to enter a password. Enter pass as the new password. Make sure that the Select Hash Method is set to Plaintext

17. Click OK.

A new entry has been added under the ou=users. The new entry is cn=Hugo Williams.

Now we need to add the remaining three users. In order to do that, just repeat the same steps earlier. Here are the details of the three remaining users.
Name: John Keats
uid: jkeats
userPassword: pass

Name: John Milton
uid: jmilton
userPassword: pass

Name: Robert Browning
uid: rbrowning
userPassword: pass
Add the Authorization Levels
We have added the personal information, as well as the usernames and passwords, for each person under the ou=users. Now, we will be adding the authorization level for each of these persons.

We'll add them under ou=groups. We'll use the groupOfUniqueNames object to represent each role.

Let's add the User role first.
1. Go to the LDAP Browser panel. Expand the Root DSE folder.

2. Expand the o=mojo entry.

3. Right-click the ou=groups entry. Select New. Select New Entry.
The Entry Creation Method window will appear.

4. Select Create entry from scratch. Click Next. The Object Classes window will appear.

5. Find the groupOfUniqueNames object. Select it then click Add.

6. Click Next. Now you need to enter a Distinguished Name (dn).
The Parent field should read ou=groups,o=mojo.

On the RDN field enter cn. On the value field enter User
The DN Preview should read cn=User,ou=groups,o=mojo

8. Click Next. The Attributes window will appear. Examine the values.

Notice there's a uniqueMember attribute. We'll be placing the Distinguished Name (dn) of our users in this entry. One uniqueMember attribute will represents one user. This means we need to add three more uniqueMember attributes for a total of four uniqueMember attributes.

9. Right-click on the same window. Select New Attribute. The Attribute Type window will appear.

10. On the Attribute type field, enter uniqueMember.

11. Click Next, then click Finish.

12. We're back on the Attributes window. We need to add two more uniqueMembers (for a total of four uniqueMembers). Repeat the same steps for adding an attribute.

13. Now we need to fill-in the values for these attributes. In each entry add the dn of each user. Here are the Distinguished Name for each user.
cn=Hugo Williams,ou=users,o=mojo
cn=John Keats,ou=users,o=mojo
cn=John Milton,ou=users,o=mojo
cn=Robert Browning,ou=users,o=mojo

14. Click Finish when you're done.

A new entry has been added under the ou=groups. The new entry is cn=User

Now we need another entry for the Admin role. We'll repeat the same steps.
1. Go to the LDAP Browser panel. Expand the Root DSE folder.

2. Expand the o=mojo entry.

3. Right-click the ou=groups entry. Select New. Select New Entry.
The Entry Creation Method window will appear.

4. Select Create entry from scratch. Click Next. The Object Classes window will appear.

5. Find the groupOfUniqueNames object. Select it then click Add.

6. Click Next. Now you need to enter a Distinguished Name (dn).
The Parent field should read ou=groups,o=mojo.

On the RDN field enter cn. On the value field enter Admin
The DN Preview should read cn=Admin,ou=groups,o=mojo

7. Click Next. The Attributes window will appear. Examine the values.

Notice there's a uniqueMember attribute. We'll be placing the Distinguished Name (dn) of our users in this entry. One uniqueMember attribute will represent one user. This means we need to add one more uniqueMember attributes for a total of two uniqueMember attributes.

8. Right-click on the same window. Select New Attribute. The Attribute Type window will appear.

9. On the Attribute type field, enter uniqueMember.

10. Click Next, then click Finish.

11. We're back on the Attributes window. We need to add one more uniqueMembers (for a total of two uniqueMembers). Repeat the same steps for adding an attribute.

12. Now we need to fill-in the values for these attributes. In each entry add the dn of each user. Here are the Distinguished Name for each user.
cn=Hugo Williams,ou=users,o=mojo
cn=John Keats,ou=users,o=mojo

13. Click Finish when you're done.

A new entry has been added under the ou=groups. The new entry is cn=Admin

Here's the final structure:

Exporting the Data
If you need to backup your data or replicate the information in your LDAP, you can export the data. When the data is exported, it's saved in LDIF format. This format is actually a human-readable file. Here's the LDIF for this tutorial:
version: 1

dn: o=mojo
objectClass: organization
objectClass: extensibleObject
objectClass: top
o: mojo

dn: ou=users,o=mojo
objectClass: extensibleObject
objectClass: organizationalUnit
objectClass: top
ou: users

dn: ou=groups,o=mojo
objectClass: extensibleObject
objectClass: organizationalUnit
objectClass: top
ou: groups

dn: cn=User,ou=groups,o=mojo
objectClass: groupOfUniqueNames
objectClass: top
cn: User
uniqueMember: cn=John Milton,ou=users,o=mojo
uniqueMember: cn=Robert Browning,ou=users,o=mojo
uniqueMember: cn=Hugo Williams,ou=users,o=mojo
uniqueMember: cn=John Keats,ou=users,o=mojo

dn: cn=Admin,ou=groups,o=mojo
objectClass: groupOfUniqueNames
objectClass: top
cn: Admin
uniqueMember: cn=Hugo Williams,ou=users,o=mojo
uniqueMember: cn=John Keats,ou=users,o=mojo

dn: cn=Robert Browning,ou=users,o=mojo
objectClass: organizationalPerson
objectClass: person
objectClass: inetOrgPerson
objectClass: top
cn: Robert Browning
sn: Browning
uid: rbrowning
userPassword:: cGFzcw==

dn: cn=John Keats,ou=users,o=mojo
objectClass: organizationalPerson
objectClass: person
objectClass: inetOrgPerson
objectClass: top
cn: John Keats
sn: Keats
uid: jkeats
userPassword:: cGFzcw==

dn: cn=Hugo Williams,ou=users,o=mojo
objectClass: organizationalPerson
objectClass: person
objectClass: inetOrgPerson
objectClass: top
cn: Hugo Williams
sn: Williams
uid: hwilliams
userPassword:: cGFzcw==

dn: cn=John Milton,ou=users,o=mojo
objectClass: organizationalPerson
objectClass: person
objectClass: inetOrgPerson
objectClass: top
cn: John Milton
sn: Milton
uid: jmilton
userPassword:: cGFzcw==
That's it. We've managed to setup our basic LDAP structure using Apache Directory Studio. We've also covered some of the popular LDAP objects.
StumpleUpon DiggIt! Del.icio.us Blinklist Yahoo Furl Technorati Simpy Spurl Reddit Google I'm reading: LDAP - Apache Directory Studio: A Basic Tutorial ~ Twitter FaceBook

Subscribe by reader Subscribe by email Share