Apache Server Implementation Guide 340 March Road Suite 600 Kanata, Ontario, Canada K2K 2E4 Tel: +1-613-599-2441 Fax: +1-613-599-2442 International Voice: +1-613-599-2441 North America Toll Free: 1-800-307-7042 www.cryptocard.com Please check CRYPTOCard web site for updates to this and other documentation.
Table of Contents Overview... 1 CRYPTO-Web Components... 2 How CRYPTO-Web authentication works... 2 CRYPTO-Web for Apache Installation... 6 Step 1: Install CRYPTO-Web... 6 Step 2: Enable HTTP/HTTPS on CRYPTO-Protocol Server... 7 Protect a Web site using the Apache Web Administration Tool... 8 Group Membership... 9 Configuring for the presence of firewalls...10 CRYPTO-Web Logon Page Customization... 11 Troubleshooting... 12 Troubleshooting Authentication Failures...12 CRYPTO-Web Apache Server Implementation Guide i
Copyright Copyright 2006, CRYPTOCard Inc All Rights Reserved. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language in any form or by any means without the written permission of CRYPTOCard Inc. Trademarks CRYPTOCard, CRYPTO-Server, CRYPTO-Web, CRYPTO-Kit, CRYPTO-Logon, CRYPTO-VPN, are either registered trademarks or trademarks of CRYPTOCard Inc. Java is a registered trademarks of Sun Microsystems, Inc.; Microsoft Windows and Windows XP/2000/2003/NT are registered trademarks of Microsoft Corporation. SecurID is a registered trademark of RSA Security. All other trademarks, trade names, service marks, service names, product names, and images mentioned and/or used herein belong to their respective owners. Publication History Date May 8, 2006 Changes Initial release Additional Information, Assistance, or Comments CRYPTOCard s technical support specialists can provide assistance when planning and implementing CRYPTOCard in your network. In addition to aiding in the selection of the appropriate authentication products, CRYPTOCard can suggest deployment procedures that provide a smooth, simple transition from existing access control systems and a satisfying experience for network users. We can also help you leverage your existing network equipment and systems to maximize your return on investment. This complimentary support service is available from your first evaluation system download. CRYPTOCard works closely with channel partners to offer worldwide Technical Support services. If you purchased this product through a CRYPTOCard channel partner, please contact your reseller directly for support needs. To contact CRYPTOCard directly: International Voice: +1-613-599-2441 North America Toll Free: 1-800-307-7042 support@cryptocard.com For information about obtaining a support contract, see our Support Web page at http://www.cryptocard.com. Related Documentation Refer to the Support & Downloads section of the CRYPTOCard website for additional documentation and interoperability guides: http://www.cryptocard.com/index.cfm?pid=364&pagename=support%20%26%20downloads CRYPTO-Web Apache Server Implementation Guide ii
Overview Compatibility and interoperability Systems protected Client browser dependencies Network architecture Supported SecurID token types Mac OS X Tiger Server running Apache Server 1.3* or 2.0 Any version of Microsoft Windows that supports Apache Server 1.3 or 2.0 Linux Apache Server 1.3 or 2.0 Ψ CRYPTO-Server 6.4 (the CRYPTO-Web package cannot be installed on a CRYPTO-Server system; it must be installed on a separate server). For Mac OS X, the CRYPTOCard Software Tools browser plug-ins only work in Safari. Apache applications, folders, pages θ Any Apache-referenced application Safari 2.0.0+ Internet Explorer 6+ Netscape Navigator 4+ Firefox 1.0.7+ Cookies and Javascript must be enabled Microsoft Java is not supported Single Apache Server Multiple Apache Servers Virtual Apache Servers SD-200, SD-520, SD-600, SD-5100, SD-6100 Encryption: DES * Apache 1.3 on Mac OS X does not function with HTTP when CRYPTO-Web is deployed in Standalone mode. This issue does not affect HTTPS. Ψ Apache 2.0 on Linux does not function with HTTPS in a Mozilla or Safari browser when CRYPTO-Web is deployed in Standalone mode. This issue doe not affect HTTPS in an IE browser or HTTP with any browser. θ Dynamically generated Web pages are not supported in Linux OS environments. CRYPTO-Web is an Apache module for an Apache 1.3 or 2.0 Web server. It sits in the data stream between the user s browser and the Web applications residing on the Web server, intercepting all resource requests. It allows access to the requested resource only after authenticating the user and CRYPTO-Web Apache Server Implementation Guide 1
verifying that the user is authorized to receive the requested resource. It may be configured to protect domain name-based and IP address-based virtual hosts. Resources are protected through the Apache Web Administration Tool located on the CRYPTO-Server. The point-and-click interface is convenient and efficient. CRYPTO-Web must be installed on each Web server it is to protect. CRYPTO-Web Components CRYPTO-Web is comprised of the following components: Apache Module: this Apache module intercepts all HTTP/HTTPS resource requests. Apache Web Administration Tool: this Web-based administration tool allows Administrators to select CRYPTOCard protection on folders and/or files within an Apache Web Server. Static or Dynamic Logon Pages: These customizable logon pages are presented when a user requests a protected resource. They provide support for manual authentication, typically used with hardware tokens and automated authentication for software, smart card, or USB token authentication. CRYPTO-Web must be used in conjunction with CRYPTO-Server 6.4 or higher. How CRYPTO-Web authentication works There are two modes of operation for CRYPTO-Web, Standalone and Web Farm mode. Standalone mode performs its authentication through a Web proxy connection to the CRYPTO-Protocol Server. This is the default option and is recommended for most installations. Web Farm mode performs its authentication by redirecting the end user to the CRYPTO-Protocol Server, which may require opening ports on your firewall. This mode is intended for situations where you wish to implement CRYPTOCard technology amongst a group of web servers. In Standalone mode, the end user communicates with the Apache server over port 80 or 443, which in turn proxies all the HTTP GET and POST requests to the Protocol Server. CRYPTO-Web Apache Server Implementation Guide 2
Network view of Standalone mode installation The Standalone mode version of CRYPTO-Web for Apache requires the use of mod_proxy modules. These modules must be either statically compiled into Apache or dynamically loaded via the httpd.conf file. The installer verifies that the mod_proxy modules are present before proceeding with the installation. The following table shows what modules are required, based on the version of Apache and the operating system: Apache 1.3 Apache 2.0 Windows mod_proxy.so mod_proxy.so mod_proxy_http.so Mac OS X libproxy.so mod_proxy.so mod_proxy_http.so Linux libproxy.so mod_proxy.so mod_proxy_http.so 1. The administrator enables CRYPTO-Web protection for a Web-based resource. 2. The user enters the URL (e.g. http://www.cryptocard.com) into his browser. 3. The incoming request is intercepted by the CRYPTO-Web Apache module. 4. CRYPTO-Web examines its internal database of protected sites to determine if CRYPTOCard authentication is required. 5. CRYPTO-Web examines the Globally Trusted Networks and IP Address List to determine if CRYPTOCard authentication can be ignored. 6. CRYPTO-Web checks for a valid CRYPTOCard per-session cookie for the Web-based resource within the user s browser. If a cookie does not exist, the user will be prompted with an authentication window. In Web Farm mode, the incoming authentication request made to http://www.cryptocard.com is redirected to http://www.cryptocard.com:8081/?http://www.cryptocard.com:80/index.html. The modified URL is the location of the CRYPTO-Protocol Server. CRYPTO-Web Apache Server Implementation Guide 3
The CRYPTO-Protocol Server is a CRYPTO-Web component used to authenticate users. It contains an HTTP and HTTPS authentication engine. The HTTP component listens on TCP ports 8081 and 8082, while the HTTPS component listens on TCP ports 9080 and 9081. Network view of Web Farm mode operation Logon Page The user is presented with a CRYPTOCard Logon page. The type of authentication page is determined by the following: If ActiveX or Netscape plug-ins are enabled, an ActiveX/Netscape plug-in Logon window is displayed. The ActiveX and Netscape plug-in are installed when the CRYPTOCard Software Tools are installed. CRYPTO-Web Apache Server Implementation Guide 4
If ActiveX/Netscape plug-ins are disabled, a static HTML logon page appears. If the user s credentials are valid and the user belongs to the CRYPTOCard group assigned to the Webbased resource, he is redirected back to the original URL (http://www.cryptocard.com). If the CRYPTOCard credentials provided are invalid, the user is presented with an Access Denied page. CRYPTO-Web Apache Server Implementation Guide 5
CRYPTO-Web for Apache Installation CRYPTO-Web can normally be installed in a matter of minutes, however proper preparation to ensure all prerequisites are met is essential. Proper configuration of DNS is necessary for proper functioning of CRYPTO-Web. If a firewall exists between the Apache server and the CRYPTO-Server, TCP ports 8080 and 4444 must be opened. CRYPTO-Server and CRYPTO-Web for Apache must not reside on the same machine. CRYPTO-Web 6.4 must be used in conjunction with CRYPTO-Server 6.4. Installing CRYPTO-Web for Apache consists of 2 steps: Step 1: Install CRYPTO-Web Step 2: Enable HTTP/HTTPS on CRYPTO-Protocol Server Step 1: Install CRYPTO-Web 1. Before running the installer, ensure that the Web server system and the CRYPTO-Server can perform forward and reverse DNS lookups by IP, fully qualified name, and hostname. This can be ensured by placing entries in the hosts file of each system. For example, in the CRYPTO-Server system hosts file, enter: <IP_addr_Apache_system> <Fully_Qual_Name_Apache_system> <Hostname_Apache_system> In the Apache system hosts file, enter: <IP_addr_CRYPTO-Server> <Fully_Qual_Name_CRYPTO-Server> <Hostname_CRYPTO-Server> 2. Run the CRYPTO-Web for Apache installer included on the CRYPTO-Server distribution on the prepared Apache server (as root, on Linux). Read and accept the license agreement to continue the installation. 3. Specify the version of the Apache Web Server. 4. Specify the location of the httpd.conf file. 5. When prompted, insert the Fully Qualified Domain Name or IP address of the CRYPTO-Server and the CRYPTO-Server Web Port (by default, 8080). CRYPTO-Web Apache Server Implementation Guide 6
If a Firewall exists between the Apache server and the CRYPTO-Server, you must open TCP port 8080 and 4444 before you continue with the installation. 6. Accept or modify the installation location for CRYPTO-Web and click Next. 7. Reboot the server when prompted, to complete the installation. Step 2: Enable HTTP/HTTPS on CRYPTO-Protocol Server CRYPTO-Web uses HTTP and/or HTTPS during the authentication process. By default, these protocols are disabled on CRYPTO-Protocol Server. They must be enabled before any authentication requests can be processed. Incorrect configuration of these items will prevent implementation of the CRYPTO- Web authentication service. 1. Log on to CRYPTO-Console and select Server System Configuration. 2. Select the PtclServer or PtclServer.IPAddress Entity. Right-click on the Protocol.HTTP.Status Key and set the Value to On. Click OK. 3. Select the PtclServer or PtclServer.IPAddress Entity. Right-click on the Protocol.HTTPS.Status Key and set the Value to On. Click OK. 4. If CRYPTO-Web for Apache is installed on a Linux platform, and CRYPTO-Server is running on Windows or Mac OS X, edit the following Entity/Key to match the specified Values: Entity Key Value HttpProtocol.Web_Server_IP Http.Root /etc/cryptocard/wwwroot HttpProtocol.Web_Server_IP Log4j,appender.HTT P_DBG.File /var/log/cryptocard/httpprotocol.dbg HttpsProtocol.Web_Server_IP Http.Root /etc/cryptocard/wwwroot HttpsProtocol.Web_Server_IP Log4j,appender.HTT PS_DBG.File /var/log/cryptocard/httpsprotocol.dbg HttpsProtocol.Web_Server_IP KeyStore.FileName /etc/cryptocard/server.keystore 5. Restart the CRYPTO-Protocol Server daemon/service on the CRYPTO-Web and CRYPTO-Server systems. On a Mac, open a Terminal window and type the following command to restart the CRYPTO- Protocol Server: sudo /Library/StartupItems/CCProtoServ/./CCProtoServ restart On a Windows platform, select Start Control Panel Administrative Tools Services, right-click on CRYPTO-Protocol Server, and select Restart. On a Linux platform, open a console session, navigate to /etc/init.d, and execute the following:./ccptcld restart 6. Open a browser and navigate to http://<crypto-server_ip_address>:8080/ CRYPTOWeb. You must log on as a CRYPTOCard user who has a valid token and who has been configured as an Operator on the CRYPTO-Server. You should now be able to expand the Apache website tree and select a resource to enable with CRYPTOCard two-factor authentication. CRYPTO-Web Apache Server Implementation Guide 7
Protect a Web site using the Apache Web Administration Tool 1. Browse to http://<crypto-server_ip_address>:8080/cryptoweb. Enter a CRYPTOCard operator name and one-time password in the Apache Web Administration Tool logon page. For security reasons, the Apache Web Administration Tool cannot be accessed from the CRYPTO-Web enabled Apache Server. It is strongly recommended that all modification be done from the CRYPTO-Server. 2. From the Apache Administration Tree, select the virtual host, folder, or file to be protected. CRYPTO-Web is hierarchical. All resources below the highest level protected on the website are automatically protected by CRYPTO-Web. 3. CRYPTO-Web authentication is enabled for a resource in three steps: CRYPTO-Web Apache Server Implementation Guide 8
a) Check the Enable CRYPTOCard Authentication check box. b) Edit the Group Settings to add CRYPTO-Server User Groups or Active Directory groups that should be permitted access to this resource (see Group membership below). c) Set the trusted IP addresses. A host in the Globally Trusted Network and IPAddress list will be permitted to access all Web resources on this Web server without authenticating through CRYPTO-Web. Fill in the range and then click Add and Submit. Group Membership The left pane lists Groups configured on CRYPTO-Server. The right pane shows CRYPTO-Server Groups permitted access to the protected resource. If no groups are listed in the Required Groups list, then all groups will be allowed to authenticate to this resource. Applying CRYPTO-Web settings updates the website Access Control List stored in the CRYPTO-Server database. CRYPTO-Web Apache Server Implementation Guide 9
Configuring for the presence of firewalls The following configuration is required if a firewall exists between the client browser and the Apache Web Server: Clients that access a CRYPTO-Web protected Apache resource must be able to connect to the Apache Web Server over TCP port 80 (and 8081 in Web Farm mode) for HTTP requests, or 443 (and 9080 in Web Farm mode) for HTTPS requests. The following configuration is required if a firewall exists between the Apache Web Server and the CRYPTO-Server. The Apache Web server must be able to connect to the CRYPTO-Server over TCP port 8080 and 4444. The Apache Web server must be able to resolve the DNS name or hostname of the CRYPTO- Server. Verify that the Primary.EJB.Url Key in the HTTP/HTTPSProtocol Entity can be resolved on the CRYPTO-Web server. If CRYPTO-Web cannot resolve the hostname or DNS name, add the entry into the /etc/hosts file. Then restart the CRYPTO-Protocol NT service. CRYPTO-Web Apache Server Implementation Guide 10
CRYPTO-Web Logon Page Customization The CRYPTO-Web logon page makes the process of logging into a secure Web application easier for CRYPTOCard software token users by eliminating the error-prone process of manually entering usernames and passwords. The logon page attempts to detect the presence of a CRYPTOCard smart card, USB, or software token. If found, the user is prompted for the token s PIN, the logon page generates the one-time password behind the scenes and submits it to the Web application for authentication. If the logon page does not detect CRYPTOCard software-based tokens, the user is prompted to manually enter his logon name and hardware-token-generated one-time password. The CRYPTO-Web logon page uses one of three possible logon components: an ActiveX control, a Netscape/Mozilla plug-in, or a static HTML logon page. The following conditions determine the type of CRYPTOCard logon page displayed to the user: If ActiveX or Netscape plug-ins are enabled, an ActiveX or Netscape plug-in logon window is displayed. If ActiveX/Netscape plug-ins are disabled, a static HTML logon page is displayed. Note: The ActiveX and Netscape plug-in are registered with the client browser during the installation of the CRYPTOCard Software Tools. The CRYPTO-Web HTML pages can be found in the /Applications/CRYPTO-Protocol/ bin/wwwroot or /Applications/CRYPTO-Server/bin/wwwroot folder (Mac), or /etc/cryptocard/wwwroot directory (Linux). If a static HTML logon page with no CRYPTOCard token detection is required, contact CRYPTOCard Technical Support. The following is a list of CRYPTO-Web logon page customization files: index.html: This is the initial CRYPTO-Web logon page presented to the user. reject.html: This page is used to display the Access Denied message. challenge.html: This is the challenge-response page. getnewpin.html: CRYPTO-Web calls this page if a server-side, server-changeable PIN (servergenerated PIN) change is detected. setnewpin.html: CRYPTO-Web calls this page if a server-side, user-changeable PIN change is detected. CRYPTO-Web Apache Server Implementation Guide 11
Troubleshooting Troubleshooting Authentication Failures Symptom Possible cause and resolution Cannot expand the Apache server tree in the Apache Web Administration Tool. CRYPTO-Web is unable to communicate with the CRYPTO-Server. Possible causes are network outage, DNS failure, CRYPTO-Server is down, or TCP Port 8080 on the CRYPTO-Server is being used by another process. Verify that the network is available and CRYPTO-Server is functioning. Verify that the domain names and port numbers are correctly configured in CRYPTO-Web and on the firewall. Valid user cannot access the protected URLs. Confirm that the user belongs to a CRYPTO-Server Group with rights to the requested resource. Verify that the Time and Date settings between the CRYPTO-Web Apache server and CRYPTO- Server are in sync. User is continually asked to authenticate. The user s OTP or PIN may be incorrect or the user may be attempting to access a URL for which he does not have sufficient rights. Alternatively, the HTTP or HTTPS protocols may not be properly configured on the CRYPTO-Protocol Server. Verify that the Time and Date settings between the CRYPTO-Web server and CRYPTO-Server are in sync. CRYPTO-Web Apache Server Implementation Guide 12
Symptom Possible cause and resolution CRYPTO-Protocol daemon/service will not start or no log files appear in the log directory. CRYPTO-Web must be able to resolve the DNS name or hostname of the CRYPTO-Server. Verify that the Primary.EJB.Url Key in the HTTP/HTTPSProtocol Entity can be resolved on the CRYPTO-Web server. If CRYPTO-Web cannot resolve the hostname or DNS name, add the entry into the etc/hosts file. Then restart the CRYPTO-Protocol daemon/service. A large grey box appears in the CRYPTOCard logon page. The CRYPTOCard logon page cannot be used with Microsoft Java (Microsoft Virtual Machine). Install the CRYPTOCard Software Tools or use the CRYPTOCard static logon page. If a static HTML logon page with no CRYPTOCard token detection is required, contact CRYPTOCard Technical Support CRYPTO-Web Apache Server Implementation Guide 13