====================================== Admin Guide for mod_ldap ====================================== TABLE OF CONTENTS Important Changes - mod_auth_ldap has been renamed to mod_authnz_ldap - New directives LDAPTrustedGlobalCert, LDAPTrustedClientCert and LDAPTrustedMode. - auth_ldap Deprecated - Important Note Overview Setup - Enabling mod_authnz_ldap/mod_ldap modules - Enabling auth_ldap module Configuration - Overview - Connect to an LDAP server - Connect to an LDAP server using SSL / TLS GUI Setup and Overview - Enabling Auth_LDAP - Overview of Auth_LDAP Configuration Troubleshooting - auth_ldap and mod_authnz_ldap/mod_ldap modules - Resources Known Problems Tuning Legal Notices ====================================== IMPORTANT CHANGES -------------------------------------- mod_auth_ldap has been renamed to mod_authnz_ldap -------------------------------------- LDAPSharedCacheFile directive is now required by mod_authnz_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 directives LDAPTrustedGlobalCert, LDAPTrustedClientCert and LDAPTrustedMode ---------------------------------------------------------------------------------- The ability to create an SSL and TLS connections to an LDAP server is defined by the directives LDAPTrustedGlobalCert, LDAPTrustedClientCert and LDAPTrustedMode. These directives specify the CA and optional client certificates to be used, as well as the type of encryption to be used on the connection (none, SSL or TLS/STARTTLS). auth_ldap Deprecated -------------------------------------- auth_ldap is deprecated and mod_authnz_ldap is the recommended module for ldap authentication. All current auth_ldap users are strongly encouraged to switch to mod_authnz_ldap. auth_ldap is being phased out and may not be available in the next release. mod_authnz_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_authnz_ldap is similar to auth_ldap with some changes and additions to the configuration directives. Caching for mod_authnz_ldap is done in mod_ldap and the caching directives differ from those in auth_ldap. Important Note -------------------------------------- By default, mod_authnz_ldap and mod_ldap are loaded by Apache if the new configuration file (httpd.conf) is picked up. ====================================== OVERVIEW -------------------------------------- auth_ldap and mod_authnz_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. - 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 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_authnz_ldap: ldap authentication module from ASF that will replace auth_ldap. mod_ldap: A companion module to mod_authnz_ldap that provides connection pooling and caching. SSL/TLS: The ability to create an SSL and TLS connections to an LDAP server is defined by the directives LDAPTrustedGlobalCert, LDAPTrustedClientCert and LDAPTrustedMode. ====================================== SETUP -------------------------------------- Enabling mod_authnz_ldap/mod_ldap modules -------------------------------------- mod_authnz_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_authnz_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/hpws22/apache/bin/apachectl stop $ /opt/hpws22/apache/bin/apachectl start HTMLNAME=ENABLING_AUTH_LDAP 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_authnz_ldap #LoadModule ldap_module modules/mod_ldap.so #LoadModule auth_ldap_module modules/mod_authnz_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/hpws22/apache/bin/apachectl stop $ /opt/hpws22/apache/bin/apachectl start ====================================== CONFIGURATION -------------------------------------- Configuration of mod_authnz_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_authnz_ldap as described below. NOTE: DO NOT CONFIGURE auth_ldap and mod_authnz_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_authnz_ldap/mod_ldap: 1. In order to protect a directory, create a directory container first, if it doesn't already exist. 2. To protect that directory, provide access authorization to the directory such as with the following directives. AuthName "My Name for protecting /path/to/my/directory" AuthType Basic Require valid-user 3. To provide authentication for the directory, specify the AuthLDAPURL directive. AuthName "My Name for protecting /path/to/my/directory" AuthType Basic Require valid-user AuthLDAPURL ldap://ldapserver.com:389/o=company.com AuthzLDAPAuthoritative off 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/hpws22/apache/conf/ldap.conf to send requests to the LDAP server. For example: # Enable the LDAP connection pool and shared # memory cache. Enable the LDAP cache status # handler. Requires that mod_ldap and mod_authnz_ldap # be loaded. Change the "yourdomain.example.com" to # match your domain. LDAPSharedCacheSize 200000 LDAPCacheEntries 1024 LDAPCacheTTL 600 LDAPOpCacheEntries 1024 LDAPOpCacheTTL 600 AuthName "Restricted Area" AuthType Basic # Specify the LDAP server and a non-SSL port AuthLDAPURL ldap://ldapserver.com:389/o=company.com AuthzLDAPAuthoritative off require valid-user 4. Stop and Start the Apache web server. Apache needs to be restarted when changing either httpd.conf or ldap.conf. /opt/hpws22/apache/bin/apachectl stop /opt/hpws22/apache/bin/apachectl start After performing the above steps, Apache will connect to and communicate with an LDAP server. HTMLNAME=SSL / TLS Connect to an LDAP server using SSL / TLS --------------------------------------------- Steps: 1. Login as root 2. Uncomment the ldap Include file at the bottom of httpd.conf. 3. Configure Apache's /opt/hpws22/apache/conf/ldap.conf to send requests to the LDAP server. The ability to create an SSL and TLS connections to an LDAP server is defined by the directives LDAPTrustedGlobalCert,LDAPTrustedClientCert and LDAPTrustedMode. These directives specify the CA and optional client certificates to be used, as well as the type of encryption to be used on the connection (none, SSL or TLS/STARTTLS). # Establish an SSL LDAP connection on port 636. Requires that # mod_ldap and mod_authnz_ldap be loaded. Change the # "yourdomain.example.com" to match your domain. LDAPTrustedGlobalCert CA_DER /certs/certfile.der SetHandler ldap-status Order deny,allow Deny from all Allow from yourdomain.example.com AuthLDAPURL ldaps://127.0.0.1/dc=example,dc=com?uid?one AuthzLDAPAuthoritative off Require valid-user # Establish a TLS LDAP connection on port 389. Requires that # mod_ldap and mod_authnz_ldap be loaded. Change the # "yourdomain.example.com" to match your domain. LDAPTrustedGlobalCert CA_DER /certs/certfile.der SetHandler ldap-status Order deny,allow Deny from all Allow from yourdomain.example.com AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one TLS AuthzLDAPAuthoritative off Require valid-user 4. Stop and start the Apache web server % /opt/hpws22/apache/bin/apachectl stop % /opt/hpws22/apache/bin/apachectl start or Uncomment #Include conf/extra/httpd-ssl.conf line in httpd.conf then % /opt/hpws22/apache/bin/apachectl start ====================================== 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_authnz_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_authnz_ldap/mod_ldap modules -------------------------------------------- auth_ldap, mod_authnz_ldap, and mod_ldap all log errors to Apache's logs/error_log. For debugging, set "LogLevel debug" in httpd.conf. Resources --------- The following resources are available for more information about auth_ldap, mod_authnz_ldap, and OpenLDAP : a) For auth_ldap, http://www.rudedog.org/auth_ldap b) For mod_authnz_ldap and mod_ldap, http://httpd.apache.org/docs-2.0/mod/mod_authnz_ldap.html http://httpd.apache.org/docs-2.0/mod/mod_ldap.html c) For OpenLDAP directory server, http://www.openldap.org ====================================== KNOWN PROBLEMS -------------------------------------- stunnel 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-_COPYRIGHT_END_REVISION 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 (eay@cryptsoft.com).