directory-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From fel...@apache.org
Subject svn commit: r1212246 - in /directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence: ./ images/ taking-advantage-of-apacheds/
Date Fri, 09 Dec 2011 04:47:48 GMT
Author: felixk
Date: Fri Dec  9 04:47:47 2011
New Revision: 1212246

URL: http://svn.apache.org/viewvc?rev=1212246&view=rev
Log:
Moving basic user guide from confluence, 4. Chapter (DIRSERVER-1678)

Added:
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_basic_auth.png
  (with props)
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_enter_url.png
  (with props)
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_tomcat_webapp_manager.png
  (with props)
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/studio_groups.png
  (with props)
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_advanced_search.png
  (with props)
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_compose.png
  (with props)
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_logo.png
  (with props)
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_options.png
  (with props)
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/tomcat-logo.png
  (with props)
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds.confluence
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/address_book_for_mozilla_thunderbird.confluence
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/integration_with_other_programs.confluence
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/user_database_for_apache_tomcat.confluence
Modified:
    directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/book.txt

Modified: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/book.txt
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/book.txt?rev=1212246&r1=1212245&r2=1212246&view=diff
==============================================================================
--- directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/book.txt
(original)
+++ directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/book.txt
Fri Dec  9 04:47:47 2011
@@ -25,7 +25,7 @@ basic-security.confluence
 basic-security/authentication_options.confluence
 basic-security/basic_authorization.confluence
 basic-security/howto_enable_ssl.confluence
-
-#managing-data-within-your-directory
-#basic-security
-#taking-advantage-of-apacheds
+taking-advantage-of-apacheds.confluence
+taking-advantage-of-apacheds/address_book_for_mozilla_thunderbird.confluence
+taking-advantage-of-apacheds/user_database_for_apache_tomcat.confluence
+taking-advantage-of-apacheds/integration_with_other_programs.confluence

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_basic_auth.png
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_basic_auth.png?rev=1212246&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_basic_auth.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_enter_url.png
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_enter_url.png?rev=1212246&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_enter_url.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_tomcat_webapp_manager.png
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_tomcat_webapp_manager.png?rev=1212246&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/firefox_tomcat_webapp_manager.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/studio_groups.png
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/studio_groups.png?rev=1212246&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/studio_groups.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_advanced_search.png
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_advanced_search.png?rev=1212246&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_advanced_search.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_compose.png
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_compose.png?rev=1212246&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_compose.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_logo.png
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_logo.png?rev=1212246&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_logo.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_options.png
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_options.png?rev=1212246&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/thunderbird_options.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/tomcat-logo.png
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/tomcat-logo.png?rev=1212246&view=auto
==============================================================================
Binary file - no diff available.

Propchange: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/images/tomcat-logo.png
------------------------------------------------------------------------------
    svn:mime-type = image/png

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds.confluence
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds.confluence?rev=1212246&view=auto
==============================================================================
--- directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds.confluence
(added)
+++ directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds.confluence
Fri Dec  9 04:47:47 2011
@@ -0,0 +1,5 @@
+h1. Taking advantage of ApacheDS
+
+This chapter contains two concrete examples on how to use Apache Directory Server with other
software programs. The E-Mail client Mozilla Thunderbird will use ApacheDS as source for an
address book. The web application server Apache Tomcat will use ApacheDS as authentication
and authorization database. 
+
+You may use these examples as a blueprint for other programs (clients, servers), which act
as an LDAP client against ApacheDS. Embedding ApacheDS, although really interesting, is not
covered in the Basic User's Guide. Check the Advanced User's Guide in order to learn about
this feature.

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/address_book_for_mozilla_thunderbird.confluence
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/address_book_for_mozilla_thunderbird.confluence?rev=1212246&view=auto
==============================================================================
--- directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/address_book_for_mozilla_thunderbird.confluence
(added)
+++ directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/address_book_for_mozilla_thunderbird.confluence
Fri Dec  9 04:47:47 2011
@@ -0,0 +1,124 @@
+h2. Address book for Mozilla Thunderbird
+
+In this section you will learn how to integrate Apache Directory Server into a mail client
in order to use the data as an address book. Mozilla Thunderbird is used as an example.
+{toc:type=list|minLevel=2|maxLevel=2}
+
+h3. E-Mail clients and Mozilla Thunderbird
+
+Integrating an LDAP server in an E-Mail client is a very traditionary task, because directories
are commonly used as user repositories within companies and organizations. Contact data is
stored for all users of the enterprise, and it is quite common to build the company's online
phone/address book on this directory. These address books are often web based application
within the intranet. But many E-Mail clients allow to connect to an LDAP based directory directly
and use its data as an address book. This seamless integration provides better user experience.
One of these clients is Mozilla Thunderbird.
+
+Technically, a mail program acts as a normal LDAP client, as described in earlier sections
(i.e. the client connects to the server and performs LDAP search operations). Therefore the
parameters you have to specify are the same. The main difference between searches with E-Mail
clients and searches with LDAP Browsers like Apache Directory Studio is that most of the complexity
of the LDAP search is hidden to the user. Hence these tools are easier to use, but less powerful.
+
+h4. Mozilla Thunderbird
+
+!images/thunderbird_logo.png!
+
+Mozilla Thunderbird is a popular open source E-Mail client which supports many platforms.
Actually it is more than just an E-Mail client (e.g. a news client as well). Features include
junk mail control and RSS reading. Learn more about this software at the projects Homepage:
[Mozilla Thunderbird|http://www.mozilla.org/products/thunderbird/|www.mozilla.org].
+
+Within this lesson we use Thunderbird primarily because of its broad support for different
operation systems and hardware platforms (and because it allows the integration of LDAP servers
as address books, of course). You may use other E-Mail clients as well. It is likely that
that allow the integration of LDAP directories as well, and even that the configuration is
similar to Thunderbird. Check your product documentation for details.
+
+h3. Prerequisites
+
+We assume that you have Mozilla Thunderbird installed on your system (or you use another
E-Mail client and are willing to assimilate the instructions to your situation). You may wish
to download the software at the homepage ([Mozilla Thunderbird|http://www.mozilla.org/products/thunderbird/|www.mozilla.org])
and install it, before proceed with this lesson.
+Furthermore you need an LDAP server up and running, which address data should be used as
an address book within your E-Mail client. For the instructions it is assumed that you have
installed Apache Directory Server as described in the first chapter of this guide and loaded
our sample data. To sum it up the following is assumed for the environment:
+* Apache Directory runs on host *zanzibar*. LDAP and listens to port *10389*
+* Anonymous access to the directory is allowed
+* Data is imported as described in section 2, Base DN is *o=sevenSeas*
+
+You may use this lesson as a blueprint to integrate other directory servers as well. At least
you need the data given above in *bold*.
+
+h3. Define Apache Directory Server as an address book
+
+h4. Open the address book
+
+After starting Mozilla Thunderbird on your workstation, go to the address book by
+* clicking the address book icon or
+* activation of the corresponding  menu item ("Tools" -- "Address Book")  or
+* pressing Ctrl+2
+
+!images/thunderbird_open_adressbook.png!
+
+h4. Define a new LDAP directory
+
+Within the address book window open the dialog to define a new LDAP directory by
+* activation of the corresponding  menu item ("File" -- "New" -- "LDAP Directory...")
+
+!images/thunderbird_new_ldap_directory_menu.png!
+
+Thunderbird opens a dialog with three tabbed panes to provide the data of the directory.
+
+h4. Provide connection data
+
+Within the "General" tab, enter basic connection data to your directory:
+* Name: A name which is used by Thunderbird within the UI, e.g. "Seven Seas"
+* Hostname: th hostname or IP address of the server, "zanzibar" in our case
+* Base DN: Search base for looking up people, we choose "ou=people,o=sevenSeas"
+* Port number: The port the LDAP provider of Apache Directory Server is listening on, "10389"
in our case
+
+!images/thunderbird_new_ldap_1.png!
+
+In this example we do not provide a Bind DN but let Thunderbird look up the users within
our directory anonymously. Apache Directory Server should be appropriately configured for
that, or you have to provide a user here.
+
+The advance tab of the dialog provides input fields for result set limits, search scope and
search filter. In our example we perform a search with subtree scope and a maximum number
of 100 entries within the result set. The search filter restricts the results to person entries
only.
+
+!images/thunderbird_new_ldap_2.png!
+
+You probably have noticed that the input fields in the two tabbed panes corresponds exactly
to the parameters for an LDAP search operation as described in this guide.
+
+h3. Using your new address book
+
+There are several ways to use your new address book. 
+
+h4. Searching
+
+The most powerful search functionality provided by Thunderbird is the _Advanced Address Book
Search_. You can start the dialog from the _Address Book_ with the menu item _Edit | Search
Addresses..._. The following dialog appears, the screen shot depicts an example search performed
against the sample data. Be sure that the right directory is selected for the _Search in:_
drop box. 
+
+!images/thunderbird_advanced_search.png!
+
+Selecting an entry and pressing the _Write_ button starts the dialog to compose a mail to
the selected person.
+
+It is also possible to search directly in the _Address Book_ as shown here:
+
+!images/thunderbird_adressbook.png!
+
+To see some data, you will have to type at least one letter on the top right input box ('H'
on the screen shot): Thunderbird does not request the directory by itself on startup to avoid
killing the client if the database is huge ...
+
+h4. Adressing
+
+It is also possible to use the E-Mail addresses from the directory directly if you compose
a mail. You can configure Thunderbird to do that via menu item _Tools | Options..._, the corresponding
tabbed pane is _Composition | Addressing_:
+
+!images/thunderbird_options.png!
+
+If configured like this, Thunderbird automatically offers E-Mail addresses from the directory
if you compose a mail and type addresses, like this: 
+
+!images/thunderbird_compose.png!
+
+Neat.
+
+h3. Troubleshooting
+
+"No matches found." 
+This is the only message you get if directory integration with Thunderbird does not function.
The tool is really weak here. Even if the connection can not be established, no error message
is shown. This holds also true for wrong configuration. 
+
+If you face a "No matches found.", the best way to detect the reason is to use another client.
Perform the same search Thunderbird uses to find entries for the address book. You can use
Apache Directory Studio for instance, or command line tools for this task. With the latter,
try something like:
+
+{noformat}
+$ ldapsearch -h zanzibar -p 10389 -b "ou=people,o=sevenSeas" -s sub "(objectClass=person)"
mail
+version: 1
+dn: cn=Cornelius Buckley,ou=people,o=sevenSeas
+mail: cbuckley@royalnavy.mod.uk
+
+dn: cn=Fletcher Christian,ou=people,o=sevenSeas
+mail: fchristi@royalnavy.mod.uk
+
+...
+{noformat}
+
+This performs an anonymous search against the sample directory and lists the E-mail addresses
of all person entries below "ou=people,o=sevenSeas".
+
+If this search operation works, Thunderbird with a configuration as described on this page
should function as well.
+
+h3. Resources
+
+* [An introduction to Thunderbird|http://opensourcearticles.com/articles/introduction_to_thunderbird],
Open Source Articles
+* [LDAP Attribute Mapping|http://www.mozilla.org/projects/thunderbird/specs/ldap.html] for
Mozilla Thunderbird
\ No newline at end of file

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/integration_with_other_programs.confluence
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/integration_with_other_programs.confluence?rev=1212246&view=auto
==============================================================================
--- directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/integration_with_other_programs.confluence
(added)
+++ directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/integration_with_other_programs.confluence
Fri Dec  9 04:47:47 2011
@@ -0,0 +1,24 @@
+h2. Integration with other programs
+
+This chapter contains references for integration with programs other than the two described.
+{toc:type=list|minLevel=2|maxLevel=2}
+
+h3. Where do you want to go from here?
+
+Using a shared and distributed directory as a global data store all over the organization
is quite common in the IT world. Integration with Mozilla Thunderbird and Apache Tomcat were
just two examples for programs which can act as LDAP client and could therefore benefit from
a central ApacheDS.
+
+As you have seen, configuration of the two was quite comparable (defining connection parameters,
LDAP search filters, etc.), and the same holds true for other software solutions as well.
+
+In this final chapter we have included some links to resources, were the configuration for
products other than Tomcat and Thunderbird are described. The list includes both open and
closed source software.
+
+h3. Resources
+
+h4. Java EE application servers
+
+ * [Securing WebLogic Server|http://e-docs.bea.com/wls/docs100/secmanage/|e-docs.bea.com],
a chapter in the online documentation for BEA WebLogic Server 10.0, describes how to set up
an LDAP server (ApacheDS for instance) as an LDAP Authentication Provider for this product.
+ * The RedBook [IBM WebSphere Application Server V6.1 Security Handbook|http://www.redbooks.ibm.com/abstracts/sg246316.html|www.redbooks.ibm.com]
(available online as PDF and HTML) contains a chapter ("2. Configuring the user registry")
which describes using an LDAP server with WebSphere Application Server V6.1. It works well
with ApacheDS.
+
+h4. Web servers
+
+* The chapter [Authentication, Authorization and Access Control|http://httpd.apache.org/docs/2.2/howto/auth.html|httpd.apache.org]
in the online documentation of Apache HTTP Server 2.2 is a good starting point to learn about
the features this solution offers. It contains links to the modules relevant to LDAP.
+

Added: directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/user_database_for_apache_tomcat.confluence
URL: http://svn.apache.org/viewvc/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/user_database_for_apache_tomcat.confluence?rev=1212246&view=auto
==============================================================================
--- directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/user_database_for_apache_tomcat.confluence
(added)
+++ directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/taking-advantage-of-apacheds/user_database_for_apache_tomcat.confluence
Fri Dec  9 04:47:47 2011
@@ -0,0 +1,228 @@
+h2. User database for Apache Tomcat
+
+In this section you will learn how to use Apache Directory Server as a user registry for
a web application server. ApacheDS holds the user data (user IDs and credentials, groups)
and performs authentication.
+
+{toc:type=list|minLevel=2|maxLevel=2}
+
+h3. Some background
+
+A common task when developing a web application is user authentication and authorization.
Parts of the application (or even the application as a whole) should only be seen by privileged
users.
+
+In order to achieve this, three things are required 
+* a mechanism for authentication, which checks the credentials provided by the user (e.g.
in a login form) 
+* a mechanism for authorization, which decides about user privileges and 
+* a data store where user information and credentials are stored
+
+For authentication and authorization Java EE (formerly known as J2EE) provides a few standard
mechanisms. A good choice for the data store is ApacheDS. LDAP is a widely adopted standard
so you can reuse your user data also for other systems.
+
+h4. Apache Tomcat
+
+According to the project's [Homepage|http://tomcat.apache.org|tomcat.apache.org], "Apache
Tomcat is the servlet container that is used in the official Reference Implementation for
the Java Servlet and JavaServer Pages technologies. The Java Servlet and JavaServer Pages
specifications are developed by Sun under the Java Community Process".
+
+!images/tomcat-logo.png!
+
+It is quite common to use Tomcat as runtime environment for Java web applications. Applications,
which are created with the help of standard technologies like Servlets, JSPs and JavaServer
Faces, or web frameworks like Apache Struts.
+
+Apache Tomcat is used as an example here, but the configuration for other server solutions
(HTTP servers among others) is quite comparable.
+
+h3. Prerequisites
+
+h4. Server (Apache Directory Server)
+
+The following assumes that ApacheDS 2.0 is configured as described [here|1.4. About the sample
configurations and sample directory data]. The sample partition "o=sevenSeas" including the
sample data should be configured and filled. If this does not hold true to your situation:
No problem. But you have to adjust the configuration parameters according your environment.
+
+Note that anonymous access to ApacheDS is used here. This leads to the simplest configuration.
If you don't want to allow anonymous access, you will have to use a bind user within the Tomcat
configuration (see notes below).
+
+h4. Client (Apache Tomcat)
+
+Although a server application, Tomcat acts as an LDAP client here. It may run on another
computer, hostname _madagascar_ is used within the following. The configuration was tested
with Apache Tomcat 6.0.14 on Java 5, but other Tomcat versions (even older ones like 5.X)
should work as well, because this part of the documentation has not changed.
+
+h3. About this example
+
+In order to demonstrate how ApacheDS works as a user registry, we will use the built in [Manager
application|http://tomcat.apache.org/tomcat-6.0-doc/manager-howto.html|tomcat.apache.org]
of Tomcat. This saves us to create our own web application for demonstration purposes. 
+
+The manager application is used for administration and deployment tasks. It's security configuration,
as usual described in the deployment descriptor of the web applications _web.xml_ contains
the following lines:
+
+{noformat}
+...
+  <!-- Define a Security Constraint on this Application -->
+  <security-constraint>
+    <web-resource-collection>
+      <web-resource-name>HTMLManger and Manager command</web-resource-name>
+      <url-pattern>/jmxproxy/*</url-pattern>
+      <url-pattern>/html/*</url-pattern>
+      ...
+    </web-resource-collection>
+    <auth-constraint>
+       <!-- NOTE:  This role is not present in the default users file -->
+       <role-name>manager</role-name>
+    </auth-constraint>
+  </security-constraint>
+
+  <!-- Define the Login Configuration for this Application -->
+  <login-config>
+    <auth-method>BASIC</auth-method>
+    <realm-name>Tomcat Manager Application</realm-name>
+  </login-config>
+
+  <!-- Security roles referenced by this web application -->
+  <security-role>
+    <description>
+      The role that is required to log in to the Manager Application
+    </description>
+    <role-name>manager</role-name>
+  </security-role>
+...
+{noformat}
+
+The security constraints enforce that only authenticated users with role _manager_ are able
to use the application. Furthermore the declarations enforce authentication with the _HTTP
Basic_ mechanism, as defined in [RFC 2617|http://tools.ietf.org/html/rfc2617|tools.ietf.org]
("HTTP Authentication: Basic and Digest Access Authentication").
+ 
+Anyway, the configuration as depicted here will work for all applications which take advantage
of the Java EE security mechanism for web applications. This holds true for your own applications
as well, if you leverage the security mechanism of Java EE. Learn more about this, for instance
in the [Java EE 5 Tutorial|http://java.sun.com/javaee/5/docs/tutorial/doc/bncas.html|java.sun.com]
at Sun.
+
+h3. Preparing the sample directory for the example
+
+As described above, users of the application must have the _manager_ role. Because we do
not want to modify the configuration of the web application, we introduce a new group _manager_
into our directory. We therefore create the following two entries within the sample partition.
Download the LDIF data [here|^tomcat_manager.ldif|tomcat_manager.ldif], and import it with
Apache Directory Studio or any other capable LDAP client.
+
+{noformat}
+dn: ou=tomcat,ou=groups,o=sevenSeas
+ou: tomcat
+objectClass: organizationalUnit
+objectClass: top
+description: Tomcat groups
+
+dn: cn=manager,ou=tomcat,ou=groups,o=sevenSeas
+objectClass: groupOfNames
+objectClass: top
+cn: manager
+member: cn=Horatio Hornblower,ou=people,o=sevenSeas
+{noformat}
+
+Horatio Hornblower is the only member of the _manager_ group. He should therefore be the
only one who is able to use the application, if configuration is finished.
+After creation of the two new entries, the partition looks like this.
+
+!images/studio_groups.png!
+
+h3. Tomcat configuration
+
+Enter Tomcat. It has a concept called [Realm|http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html|tomcat.apache.org]
for user registries. Different implementations exist for different data stores. The one designated
to LDAP is called _JNDIRealm_.
+
+In order to use our ApacheDS as user data storage, edit the _server.xml_ configuration file
of your Tomcat instance (located in _<TOMCAT_HOME>/conf_). You can comment out other
realms and add a _JNDIRealm_ within the _Engine_ element like this:
+
+{noformat}
+...
+<Engine name="Catalina" defaultHost="localhost">
+  ...
+  <Realm
+    className="org.apache.catalina.realm.JNDIRealm"
+    connectionURL="ldap://zanzibar:10389/o=sevenSeas"
+  
+    userBase="ou=people"
+    userSearch="(&amp;(objectClass=inetOrgPerson)(uid={0}))"
+    userSubtree="true"
+  
+    roleBase="ou=groups"
+    roleName="cn"
+    roleSearch="(&amp;(objectClass=groupOfNames)(member={0}))"
+    roleSubtree="true"
+  />
+  ...
+</Engine>
+...
+{noformat}
+
+Note that this realm, if placed within <Engine /> will rule the whole Tomcat instance.
Other scopes are possible as well, feel free to learn more about this topic from the pache
Tomcat [Realm Configuration HOW-TO|http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html|tomcat.apache.org].

+
+Download the _server.xml_ used for our tests [here|^server.xml|server.xml].
+
+Let's look how this configuration works.
+
+h4. Connectivity
+
+The _connectionURL_ attribute holds the connection data (hostname, port, base DN) to our
ApacheDS as an LDAP URL. Tomcat will bind to the server anonymously. It is possible to use
a technical user as well (attributes _connectionName_, _connectionPassword_, see Tomcat Realm
documentation for details).
+
+h4. Authentication
+
+If configured like this, Tomcat will perform exactly the steps described in [3.1. Authentication
options] (see "How to authenticate a user by uid and password?") in order to authenticate
a user.
+
+First of all, Tomcat searches anonymously the entry of the user with the help of an LDAP
search operation. The following parameters of the _JNDIRealm_ configuration above govern the
search:
+
+|| Parameter || Value in example || Comments ||
+|userBase|ou=people|Search base. Combined with the connection parameter, this leads to "ou=people,o=sevenSeas"|
+|userSearch|(&amp;(objectClass=inetOrgPerson)(uid=\{0\}))|Search filter. Use '&amp;amp;'
instead of '&' due to XML. '\{0\}' will be replaced by Tomcat with the given user ID |
+|userSubtree|true|Search the whole subtree |
+
+You can perform the corresponding search with an arbitrary LDAP client. This method is a
good practice in case of trouble shooting. This is how it looks with a command line tool:
+
+{noformat}
+$ ldapsearch -h zanzibar -p 10389 -b "ou=people,o=sevenSeas" \\
+    -s sub "(&(objectClass=inetOrgPerson)(uid=hhornblo))" cn
+version: 1
+dn: cn=Horatio Hornblower,ou=people,o=sevenSeas
+cn: Horatio Hornblower
+$
+{noformat}
+
+The search finds DN _cn=Horatio Hornblower,ou=people,o=sevenSeas_ for user ID _hhornblo_,
and so would Apache Tomcat.
+
+In the next step, Tomcat would use this DN to bind against ApacheDS with the given password.
If this is successful, the user is authenticated.
+
+h4. Authorization
+
+With this configuration, roles will be determined by Tomcat with a group search. The following
parameters of the _JNDIRealm_ configuration above govern this second search:
+
+|| Parameter || Value in example || Comments ||
+|roleBase|ou=groups|Search base. Combined with the connection parameter, this leads to "ou=groups,o=sevenSeas"|
+|roleName|cn|attribute within group entries which carries the role name|
+|roleSearch|(&amp;(objectClass=groupOfNames)(member=\{0\}))|Search filter. Use '&amp;amp;'
instead of '&' due to XML. '\{0\}' will be replaced by Tomcat with the DN of the authenticated
user |
+|roleSubtree|true|Search the whole subtree |
+
+Again you can perform the corresponding search with an arbitrary LDAP client. It demonstrates
how Tomcat will determine the roles for a given user. This is how it looks with a command
line tool for user _hhornblo_ (DN _cn=Horatio Hornblower,ou=people,o=sevenSeas_):
+
+{noformat}
+$ ldapsearch -h zanzibar -p 10389 -b "ou=groups,o=sevenSeas" -s sub \\
+  "(&(objectClass=groupOfNames)(member=cn=Horatio Hornblower,ou=people,o=sevenSeas))"
cn
+version: 1
+version: 1
+dn: cn=HMS Lydia,ou=crews,ou=groups,o=sevenSeas
+cn: HMS Lydia
+
+dn: cn=manager,ou=tomcat,ou=groups,o=sevenSeas
+cn: manager
+$
+{noformat}
+
+The search finds two groups for user _hhornblo_, one of them is the _manager_ group created
for Tomcat. So _hhornblo_ should be able to log on to Tomcat and work with this application.
Let's try it out!
+
+h3. Verification
+
+After modification of the Tomcat configuration (_server.xml_), you have to restart Tomcat.
Check if it starts up successfully. Point with a web browser to the server. A default Tomcat
presents a welcome page, if you use the URL _http://<hostname>:8080/_.
+
+!images/firefox_enter_url.png!
+
+If you click to _Tomcat Manager_ (in the _Administration_ box on the left of the welcome
screen), or type _http://<hostname>:8080/manager/html/_ as URL, the authentication dialog
of the browser shows up (at least it should).
+
+!images/firefox_basic_auth.png!
+
+Enter _hhornblo_ as user name and the password (default in the sample data is "pass"). Press
_OK_. If everything works, Tomcat should perform authentication and authorization as described
above, and present the Manager web application:
+
+!images/firefox_tomcat_webapp_manager.png!
+
+If it does not work (status code 403, for instance), check the log files of Apache Tomcat.
Performing the LDAP searches as described above may help to find the problem.
+
+h3. Other configuration scenarios
+
+The configuration above is just _one_ simple example. In your environment, it may not be
appropriate. For instance
+
+* Communication between Apache Tomcat and ApacheDS should take place via SSL (LDAPS)
+* Anonymous access is not allowed
+* Authentication should take place differently (with a compare operation instead of a simple
bind, for instance)
+* Authorization should be handled differently (with the help of a multiple role attribute
for user entries, for instance)
+* ...
+
+Learn more about the configuration options of Apache Tomcat's JNDIRealm in the [Realm Configuration
HOW-TO|http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html|tomcat.apache.org].
+
+h3. Resources
+
+* [Apache Tomcat|http://tomcat.apache.org|tomcat.apache.org] Homepage
+* The Apache Tomcat [Realm Configuration HOW-TO|http://tomcat.apache.org/tomcat-6.0-doc/realm-howto.html|tomcat.apache.org]
conatins all configuration options for the _JNDIRealm_ used here
+* [The Java EE 5 Tutorial|http://java.sun.com/javaee/5/docs/tutorial/doc/|java.sun.com] is
written with Sun Java System Application Server in mind. But it includes very helpful information
on how to secure Java web applications
\ No newline at end of file



Mime
View raw message