|
|
Admin Guide for auth_ldap 1.5.4 and mod_auth_ldap
TABLE OF CONTENTS
Important Changes
- mod_auth_ldap requires new directive
- New Stunnel
- auth_ldap Deprecated
- Important Note
Overview
Setup
- Enabling mod_auth_ldap/mod_ldap modules
- Enabling auth_ldap module
Configuration
- Overview
- Connect to an LDAP server
- Connect to an LDAP server using SSL
- Connect to an OpenLDAP server using TLS
GUI Setup and Overview
- Enabling Auth_LDAP
- Overview of Auth_LDAP Configuration
Troubleshooting
- auth_ldap and mod_auth_ldap/mod_ldap modules
- Stunnel
- Resources
Known Problems
Tuning
Legal Notices
IMPORTANT CHANGES
mod_auth_ldap requires new directive
LDAPSharedCacheFile directive is now required by mod_auth_ldap. The name specified by
this directive is used to create a shared memory for ldap caching.
The default value in ldap.conf is logs/ldap_cache.
New Stunnel
Stunnel has been upgraded to version 4.04. Stunnel 4.x
reflects an architectural change with a new configuration file
format that replaces the 3.x command line format. This change
affects how stunnel is configured and started. The previous
stunnel control script (stunnel_ctl.sh) has been replaced
by an stunnel configuration file, stunnel.conf, and an stunnel
startup script, stunnel.init. Please see the following section
for more information LDAP server using SSL section.
auth_ldap Deprecated
auth_ldap is deprecated and mod_auth_ldap is the recommended
module for ldap authentication. All current auth_ldap users
are strongly encouraged to switch to mod_auth_ldap. auth_ldap
is being phased out and may not be available in the next
release.
mod_auth_ldap is a new module from the Apache Software Foundation
(ASF). Its used in conjunction with the mod_ldap caching module.
Together, these two modules provide thread-safe, SSL-enabled
authentication against an LDAP directory server.
mod_auth_ldap is similar to auth_ldap with some changes and additions
to the configuration directives. Caching for mod_auth_ldap is done in
mod_ldap and the caching directives differ from those in auth_ldap.
Important Note
By default, mod_auth_ldap and mod_ldap are loaded by Apache if the new
configuration file (httpd.conf) is picked up.
OVERVIEW
auth_ldap and mod_auth_ldap are authentication modules for Apache that
allow HTTP client authentication using entries in an LDAP directory server.
The LDAP server can either be on the same server as Apache (local) or on a
different server (remote). Both modules have these characteristics:
- Can be used with iPlanet (Netscape) Directory Server or
OpenLDAP directory server.
- Built using OpenLDAP SDK 2.1.22 OpenLDAP SDK is located
in /opt/hpws/apache/ldap/lib.
- Can send either encrypted or non-encrypted requests to
an LDAP server. Encryption provides secure transactions
between Apache and the LDAP server. Either SSL or TLS
can be used for encryption.
- Use Stunnel for SSL encryption
- Use configuration directives in conf/ldap.conf
auth_ldap:
ldap authentication module from rudedog.com. This module is not delivered
from HP-UX Apache based Web Server Version 2.0.58.00 onwards.
mod_auth_ldap:
ldap authentication module from ASF that will replace auth_ldap.
mod_ldap:
A companion module to mod_auth_ldap that provides connection pooling
and caching.
SSL:
SSL is provided by the Stunnel utility that runs on the web server
machine and acts as an intermediary between Apache and the LDAP server.
Stunnel encrypts a request after getting it from the authentication
module and before forwarding it to the LDAP server.
SSL can be used with the OpenLDAP directory server or with Netscape
Directory Server.
Stunnel:
Stunnel is version 4.04. The binary, /opt/hpws/apache/stunnel/sbin/stunnel,
its control script, stunnel.init, and its corresponding configuration file,
conf/stunnel.conf, are supported for use with auth_ldap and
mod_auth_ldap/mod_ldap. Stunnel has not been tested for general use and
may not be available in the future.
TLS:
TLS encryption capability is provided through the OpenLDAP SDK that is
compiled into the authentication modules. SSL libraries are used to do
the encryption.
TLS can be used with the OpenLDAP directory sever.
SETUP
Enabling mod_auth_ldap/mod_ldap modules
mod_auth_ldap and mod_ldap are made available through httpd.conf.
To use these modules:
1. Verify the two LDAP LoadModule directives are uncommented
in httpd.conf:
LoadModule ldap_module modules/mod_ldap.so
LoadModule auth_ldap_module modules/mod_auth_ldap.so
2. Uncomment the Include file in httpd.conf to make ldap authentication
available,
Include conf/ldap.conf
3. Stop and start Apache,
$ /opt/hpws/apache/bin/apachectl stop
$ /opt/hpws/apache/bin/apachectl start
Enabling auth_ldap module
auth_ldap is made available through httpd.conf. The LoadModule directive
is in conf/ldap.conf. To use auth_ldap follow these steps:
1. Comment the two LoadModule directives for mod_auth_ldap
#LoadModule ldap_module modules/mod_ldap.so
#LoadModule auth_ldap_module modules/mod_auth_ldap.so
2. Uncomment the include file in httpd.conf to make ldap authentication
available,
Include conf/ldap.conf
3. Stop and start Apache,
$ /opt/hpws/apache/bin/apachectl stop
$ /opt/hpws/apache/bin/apachectl start
CONFIGURATION
Configuration of mod_auth_ldap and auth_ldap is done by
adding configuration directives to the conf/ldap.conf file.
LDAP authentication can be set up to access an LDAP server securely
or without security. Configure auth_ldap or mod_auth_ldap as
described below.
NOTE: DO NOT CONFIGURE auth_ldap and mod_auth_ldap/mod_ldap at the SAME TIME.
Overview
LDAP authentication allows you to protect a certain directory, location,
or a set of files. The steps below provide a quick overview of how to
protect a directory. These steps can be used with auth_ldap or
mod_auth_ldap/mod_ldap:
1. In order to protect a directory, create a directory
container first, if it doesn't already exist.
<Directory "/path/to/my/directory">
</Directory>
2. To protect that directory, provide access authorization
to the directory such as with the following directives.
<Directory "/path/to/my/directory">
AuthName "My Name for protecting /path/to/my/directory"
AuthType Basic
Require valid-user
</Directory>
3. To provide authentication for the directory, specify the
AuthLDAPURL directive.
<Directory "/path/to/my/directory">
AuthName "My Name for protecting /path/to/my/directory"
AuthType Basic
Require valid-user
AuthLDAPURL ldap://ldapserver.com:389/o=company.com
</Directory>
Connect to an LDAP server
These are the steps for configuring the HP-UX Apache-based Web Server
to authenticate _without_ using a secure connection between the
web server and the LDAP server.
Steps:
1. Login as root
2. Uncomment the ldap Include file at the bottom of httpd.conf.
Include conf/ldap.conf
3. Configure Apache's /opt/hpws/apache/conf/ldap.conf to send requests
to the LDAP server.
For example:
<Location /ldaptest>
AuthName "Restricted Area"
AuthType Basic
# Specify the LDAP server and a non-SSL port
AuthLDAPURL ldap://ldapserver.com:389/o=company.com
require valid-user
</Location>
4. Stop and Start the Apache web server. Apache needs to be restarted
when changing either httpd.conf or ldap.conf.
/opt/hpws/apache/bin/apachectl stop
/opt/hpws/apache/bin/apachectl start
After performing the above steps, Apache will connect to and communicate
with an LDAP server.
Connect to an LDAP server using SSL
The ldap authentication modules use the Stunnel utility as an intermediary
between Apache and the LDAP server. Stunnel provides security by encrypting
a request before it is sent to the LDAP server. It works independently
of the SSL between the HTTP client and Apache.
Stunnel runs on the web server machine and listens for requests sent by
auth_ldap or mod_auth_ldap to the port configured in ldap.conf. Stunnel
then encrypts and forwards the encrypted request to the LDAP server using
the LDAP server's secure port ldaps://.
Steps:
1. Login as root
2. Uncomment the ldap Include file at the bottom of httpd.conf.
Include conf/ldap.conf
3. Configure Apache /opt/hpws/apache/conf/ldap.conf to forward ldap
requests to Stunnel. Stunnel should be running on the same machine
as Apache.
For example:
<Location /ldaptest>
AuthName "Restricted Area"
AuthType Basic
# Stunnel listens on localhost:7777
AuthLDAPURL ldap://localhost:7777/o=company.com
require valid-user
</Location>
NOTE: If you are running an LDAP server on the same machine as Apache,
you may already be using port 389 or 636. Be sure to choose
an unused port for Stunnel (see Troubleshooting).
4. Now configure Stunnel by editing /opt/hpws/apache/conf/stunnel.conf.
Stunnel must accept connections from Apache on the same port that is
configured in ldap.conf (i.e. 7777).
The outgoing connection to the LDAP server must also be configured
with the correct LDAP server address and port.
To accept requests on 7777 and send to myserver.com on port 636, change
the "Service-level configuration" for "ldap" to:
# Service-level configuration
[ldap]
accept = 127.0.0.1:7777
connect = myserver.com:636
5. Start Stunnel using the stunnel.init script. Each time
Stunnel is started a random file is created in
/opt/hpws/apache/stunnel/.stunnel.rnd to create a new random seed.
% /opt/hpws/apache/stunnel/stunnel.init start
To verify that Stunnel is running do,
% ps -aef | grep stunnel | grep -v grep
The output should look something like the following,
www 28953 1 0 12:50:50 ? 0:00 /opt/hpws/apache/stunnel/sbin/stunnel /opt/hpws/apache/conf/stunnel.conf
6. Stop and start the Apache web server
% /opt/hpws/apache/bin/apachectl stop
% /opt/hpws/apache/bin/apachectl start
or
% /opt/hpws/apache/bin/apachectl startssl
NOTE: You may want to start Apache in SSL mode for secure
transactions between the HTTP client and Apache.
After performing the above mentioned steps, Stunnel will forward all LDAP
authorization queries to an LDAP server using SSL.
Stopping Stunnel:
Use the stunnel.init script to stop Stunnel. This kills the
logs/stunnel.pid process
% /opt/hpws/apache/stunnel/stunnel.init stop
Connect to an OpenLDAP server using TLS
TLS can be used with auth_ldap for secure connections to an OpenLDAP server.
1. Login as root
2. Enable auth_ldap. See section
Enabling auth_ldap
3. Configure Apache /opt/hpws/apache/conf/ldap.conf to use TLS
For example:
<Location /ldaptest>
AuthName "Restricted Area"
AuthType Basic
AuthLDAPURL ldap://your_openldap_server:636/o=your-organization.com
# Enable TLS
AuthLDAPStartTLS on
require valid-user
</Location>
4. Stop and start the Apache web server
% /opt/hpws/apache/bin/apachectl stop
% /opt/hpws/apache/bin/apachectl start
or
% /opt/hpws/apache/bin/apachectl startssl
NOTE: You may want to start Apache in SSL mode for secure
transactions between the HTTP client and Apache.
After performing the above steps, auth_ldap will connect to and communicate
with an OpenLDAP server using TLS.
GUI SETUP AND OVERVIEW
Only auth_ldap can be completely configured using the HP-UX Webmin-based Admin
GUI instead of the command line as described above. Partial support is
available for configuring new mod_auth_ldap and mod_ldap modules through
HP-UX Webmin-based Admin.
Enabling Auth_LDAP
To configure auth_ldap using HP-UX Webmin-based Admin GUI,
1. Start HP-UX Webmin-based Admin if it isn't already running.
2. Access HP-UX Webmin-based Admin at http://yourserver.com:10000
3. In the "HP-UX Web Server Suite" section,
click on the "HP-UX Apache-based Web Server" icon
4. In the "HP-UX Apache-based Web Server" section,
click on the "Apache Modules" icon
5. In the "Home > Global > Apache Modules" section,
click on "auth_ldap" check-box
click on the "Save" button in the bottom
click on "Restart Apache"/"Start Apache" link on the top
Note: Sometimes, you may have to actually "Stop Apache" and
"Start Apache" in two different steps for the changes
to take effect.
Overview of Auth_LDAP Configuration
Auth_LDAP allows you to protect a certain directory, location or a
set of files. The steps below provide you a quick overview of how
one can protect a directory.
0. Start HP-UX Webmin-based Admin if it isn't already running.
Access HP-UX Webmin-based Admin at http://yourserver.com:10000/
1. In order to protect a directory, you need to create a directory
container directive first, if it doesn't already exist.
In the "HP-UX Web Server Suite" section,
click on the "HP-UX Apache-based Web Server" icon
In the "HP-UX Apache-based Web Server" section,
click on the virtual server of your choice. For example, you
could click on "default server"
In the "Home > default server" section,
click on the directory icon of the directory of your choice.
if one doesn't exist, then create a directory icon by
filling out the "Create Per-Directory, Files or Location Options"
table. Once created, click on the directory icon just created.
2. To protect that directory, you need to provide any access
authorization to the directory, you need to provide the following
directives.
In the "Home > default server > Directory /path/to/my/directory" section,
click on "Auth_LDAP" icon
In the "Home > default server > Directory /path/to/my/directory > Auth_LDAP" section,
set-up the following fields:
- "Restrict access by login" to "All valid users"
- "Authentication type" to "basic"
- "Authentication realm name" to a string like:
My Name for protecting /path/to/my/directory
3. To provide authentication for the directory using Auth_LDAP, you
need to specify the AuthLDAPURL directive.
In the "Home > default server > Directory /path/to/my/directory > Auth_LDAP" section,
set-up the following fields:
- "URL specifying LDAP search parameters" to point to the
LDAP database like:
ldap://ldapserver.com:389/o=company.com
Since LDAP authentication works in conjunction with the other authorization
modules that are included with HP-UX Apache-based Web Server, you may also
want to configure additional authorization features.
TROUBLESHOOTING
auth_ldap and mod_auth_ldap/mod_ldap modules
auth_ldap, mod_auth_ldap, and mod_ldap all log errors to Apache's
logs/error_log. For debugging, set "LogLevel debug" in httpd.conf.
Stunnel
# Some debugging stuff
debug = 7
output = /opt/hpws/apache/logs/stunnel.log
Use stunnel -help for the Stunnel help facility to see its usage,
% /opt/hpws/apache/stunnel/sbin/stunnel -help
Man pages are also available by doing the following:
% export MANPATH=$MANPATH:/opt/hpws/apache/man
% man stunnel
To get more information about what Stunnel is doing, edit the
stunnel.init script to run Stunnel with more output logged to
the stunnel.log file. The maximum level is 7.
# Some debugging stuff
debug = 7
output = /opt/hpws/apache/logs/stunnel.log
Make sure Stunnel is not trying to read on a port that is
already in use. For example, to determine if port 7777 is
being used:
% netstat -a | grep 7777
Resources
The following resources are available for more information
about auth_ldap, mod_auth_ldap, OpenLDAP, and Stunnel:
a) For auth_ldap,
http://www.rudedog.org/auth_ldap
b) For mod_auth_ldap and mod_ldap,
http://httpd.apache.org/docs-2.0/mod/mod_auth_ldap.html
http://httpd.apache.org/docs-2.0/mod/mod_ldap.html
c) For OpenLDAP directory server,
http://www.openldap.org
d) For the Stunnel program,
http://www.stunnel.org
KNOWN PROBLEMS
TLS is not supported in this release.
TUNING
Performance can be boosted by tuning the LDAP server.
***************************************************************************
LEGAL NOTICES
The information in this document is subject to change without notice.
WARRANTY DISCLAIMER
HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS
INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Hewlett-Packard
shall not be liable for errors contained herein or for direct, indirect,
special, incidental or consequential damages in connection with the
furnishing, performance or use of this material.
RESTRICTED RIGHTS LEGEND
Use, duplication or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in
Technical Data and Computer Software clause at DFARS 252.227-7013 for DOD
agencies. Rights for non-DOD U.S. Government Department and Agencies are
as set forth in FAR 52.227-19 (c)(1,2).
COPYRIGHT NOTICES
Copyright 2001-2007 Hewlett-Packard Development Company, L.P.
This document contains information which is protected by copyright.
All Rights Reserved. Reproduction, adaptation, or translation without
prior written permission is prohibited, except as allowed under the
copyright laws.
TRADEMARK NOTICES
UNIX is a registered trademark in the United States and other countries,
licensed exclusively through X/Open Company Limited.
Java and all Java-based trademarks and logos are trademarks or
registered trademarks of Sun Microsystems, Inc. in the U.S. and
other countries.
ACKNOWLEDGEMENTS
This product includes software developed by the Apache Software Foundation.
This documentation is based on information from the Apache Software Foundation
(http://www.apache.org).
This product includes software developed by the OpenLDAP Project
(http://www.openldap.org).
This product includes software developed by the OpenSSL Project for use
in the OpenSSL Toolkit (http://www.openssl.org).
This product includes cryptographic software written by Eric Young
([email protected]).
|
