We describe the installation of the Yale Central Authentication System. This has a two part architecture, with clients protecting resources and a central server providing the authentication (a design common to such systems). The system, as provided by Yale, needs an authentication connector to be added; the SECURe project has provided a connector for the authbroker system, which is configurable to use a wide range of authentication backends.
Time required: 1 day.
Skill required: Some sysadmin experience to install if no modifications to system from those described below; HTML skills; JAVA/Tomcat programming experience (if modifications are required).
All the software described here needs to be installed on the same machine.
As detailed below, the software can be obtained from the SECURe web site. The version provided version includes those modifications that render it easier to install. Log in as a non-root user.
Assuming that you have the wget utility installed (a standard part of most Linux distributions), type:
% wget http://www.angel.ac.uk/SECURe/software/authbroker.tar.gz
(the other outputs, which are basically identical, are supressed), then:
% wget http://www.angel.ac.uk/SECURe/software/cas-server.tar.gz
To open the software archive ready for configuration, type:
% tar zxvf authbroker.tar.gz
The authbroker needs to be configured to use your institutional directory service as its backend. It is possible to use multiple backends for the authbroker (see the documentation file authbroker.txt for more information). The version of the authbroker available from the SECURe website comes with a simple configuration to use a single LDAP server as both authentication and directory server. All that needs to be done is to edit the configuration file to point to your institutional LDAP directory. To do this, first move to the directory containing the authbroker configuration file:
% cd authbroker/conf
and open the configuration file in an editor:
% vi auth.config
Lines in this file which begin with '#' are comments and can be freely edited. You may well find it useful to have information about which machine and configuration file are used by the authbroker, as there is in the example file in the download, and also details about the maintainer. The format of the instructions in the configuration file is essentially XML, and is divided into three sections.
The first section contains general configuration details. The only details here that may need to be changed are the location of the log file (the errlog tag) and the port number on which the authbroker will receive requests. The authbroker is set to receive connections on port 1252 by default. If this is not suitable for the machine on which the authbroker is to be hosted, then the port setting should be changed to one not currently in use. (Note that the authbroker should not be run on ports below 1000.)
To understand the remaining sections requires some knowledge of the architecture of the authbroker. There are two types of connection which the authbroker can make, one to check authentication and the other to retrieve the directory information. The second configuration section describes the authentication handlers, and the third describes the directory handlers. The directory information returned by the authbroker is not required by the CAS, so there is no need to change this. It connects to a dummy directory service. However, the authentication details do need to be altered to connect to your LDAP server. For more complex changes, the authbroker archive contains a file authbroker.txt which contains more detailed information about authbroker configuration.
There are two things which you may wish to edit about the authservice information: the usernamesuffix (and possibly the usernamefield, though this is unlikely), and the location of the LDAP server. The rest of the data is either not used by the CAS, or has sensible default values. The default LDAP port is 389, so it is not necessary to include this information if that is the port used by your LDAP server.
To start the authbroker, go up one directory level thus,
% cd ..
and type
% ./auth.pl
You will probably want to test the authbroker. The quickest way to do this is to connect to it via telnet and enter a query:
% telnet localhost 1252 Trying 127.0.0.1... Connected to localhost. Escape character is '^]'.
Following this, enter the query (which covers several lines and is followed by a blank line):
<Xrep> <logonRequest> <requestSource>user</requestSource> <sessionID>CAS</sessionID> <userID>username</userID> <password>password</password> <ipAddress>123.123.123.123</ipAddress> </logonRequest> </Xrep>
Most items in this request should be self explanatory (session ID is used in the authbroker logs for tracking purposes).
For an erroneous userID/password, you will now see:
<Xrep>
<diagnostic>
<diagnosticCode>3</diagnosticCode>
<diagnosticString>No authentication method matches</diagnosticString>
<diagnosticAddInfo></diagnosticAddInfo>
</diagnostic>
</Xrep>Connection closed by foreign host.
while a valid combination will result in an output like:
<Xrep><logonResponse><group>People</group><group>all</group><group>all.lse</group> <group>all.lse.ac.uk</group><group>London School of Economics</group> <userinfo><authsource>LSEAD</authsource><ip>123.123.123.123</ip></userinfo> <timeOut>600</timeOut></logonResponse></Xrep>Connection closed by foreign host.
Problem: Chosen port in use
Symptom: Start-up produces the error:
% ./auth.pl Name "main::libdir" used only once: possible typo at ./auth.pl line 278. Starting up daemon on port 1252 bind: Address already in use at ./auth.pl line 64.
Solution: This either means that the authbroker is already running, or that some other software is using the port. To ascertain which is the case, the easiest thing to do is to check if there is an authbroker process running on the machine. To get the process ID of the most recently started authbroker, type:
% cat auth.pl.pid 13654
and then to see if it is still running type:
% ps 13654 PID TTY STAT TIME COMMAND 13654 ? S 0:00 /usr/bin/perl -Tw ./auth.pl
(there is no second line in the output when there is no matching process). If you wish to start a new authbroker (e.g. if you have edited the configuration), you will need to stop the existing one:
% kill -9 13654
after which you should be able to start up the authbroker as normal. If the authbroker is not running, you will need to change the port number in the configuration file.
Problem: Unable to connect to authbroker
Symptom: Telnet to the authbroker produces the error:
% telnet localhost 1252 Trying 127.0.0.1... telnet: Unable to connect to remote host: Connection refused
Solution: Note that your firewall may mean that you might see this error when telneting from somewhere other than the machine which has the authbroker on it. Otherwise, this error probably means that the authbroker is no longer running and needs to be restarted (see above for how to check this).
Problem: Missing perl library
Symptom: Error message complaining that it's not possible to find libraries:
[EXAMPLE needs to be added]
Solution: This depends on which libraries are not found, as the authbroker contains perl libraries of its own. These should automatically be picked up, but edit the authrc file if not. (The libraries are listed at the end of the file, and the perl variable $current refers to the directory in which the authbroker is installed.) If third party libraries such as Net::LDAP are missing, then they can be downloaded from the Comprehensive Perl Archive Network (CPAN) and installed.
Now, open the CAS server software archive:
tar zxvf cas-server.tar.gz
and change to the newly created directory:
cd cas-server
All that is needed to deploy CAS is to copy the cas.war file provided in the download to the appropriate part of the Tomcat system and then restart Tomcat. Tomcat will then automatically install the software. You are likely to need to be the root user to perform these actions. It is also possible to load the CAS software using the manager application that is part of the Tomcat installation.
Tomcat is likely to be in one of two locations, depending on how it was installed. If your copy of the software was installed from source, it is likely to be in /usr/local/tomcat. If, however, it was installed as a RedHat RPM, it should be in /var/tomcatn, where n is the major version number (i.e. 4 for Tomcat 4.1.0, etc.). Set the environment variable TOMCAT_HOME to this location, for example:
# export TOMCAT_HOME=/usr/local/tomcat
for the source code installation.
The .war file you need to copy to the Tomcat webapps directory is named cas.war. See our associated Tomcat documentation for details on how to deploy the software archive.
The main configuration file for the CAS is named web.xml, and is found at $TOMCAT_HOME/webapps/cas/WEB-INF/web.xml. The important change to make is to the authHandler setting, which should now be uk.ac.lse.cas.authbroker. You may wish to change the timeout parameters further down the file, but there is no essential need for this. (The times are in seconds.) The other settings basically describe which web pages to use as templates for various actions, and should be left alone. To implement the changes, restart tomcat as described above.
Configuration for the CAS is also needed in the Apache server configuration file. The standard location for the server configuration is /etc/httpd/conf/httpd.conf, though you may have a separate file for mod_jk configuration (such as /etc/httpd/conf/mod_jk.conf). Whichever file it is should have a set of directives in the section for the secure web server configuration that start with Jk. This should include something like the following (with allowance made for possible differences in the location of Tomcat and Apache):
<IfModule !mod_jk.c> LoadModule jk_module libexec/mod_jk.so </IfModule> JkWorkersFile "/usr/local/tomcat/conf/jk/workers.properties" JkLogFile "/usr/local/apache/logs/mod_jk.log" JkLogLevel emerg
At the end of this group of directives, you need to add:
JkMount /cas/* ajp13
Restart the web server to apply the changes:
# /sbin/service httpd restart
The best way to test the CAS is via a web browser. Full testing is only possible once a CAS client has been installed to protect data, but it is possible to see whether the login process proceeds as intended.
To access the login page on your server, enter the URL https://yourservername.ac.uk/cas/login in a web browser, and complete the form with a valid username and password. You should see the message "You have been logged in successfully". If there is a problem, you will see the error "Sorry, you entered an invalid NetID or password. Please try again". (Of course, you may have failed to get through to the web server in the first place.)
Possible problems with the server and suggestions for solving them are described in the following table:
| Problem | Symptoms | Solution |
|---|---|---|
| Machine down or disconnected from the network | The console is inaccessible (machine down), or it is impossible to access the machine across the network with any client (including 'ping'). | Try rebooting the machine. If this doesn't work, refer to your installation documentation or local experts for help on configuring your network connection. |
| Web server not running | You can connect to the machine (e.g. with an ssh client) but not access the web server. (Try accessing port 80 with "telnet" to make sure this is the case; you will get a "Connection refused" response if the web server is not accessible.) | Restart the web server. You may see error messages on restart, particularly if there is an error in the web server configuration file. You will need to deal with these before the web server will run properly. |
| Web server not receiving https connections | You can connect with a web browser to "http://secure.institution.ac.uk/" but not to "https://secure.institution.ac.uk" | Since most mod_ssl configuration errors (such as not including the module) would make the web server fail to start up, this is likely to be due to omitting to make the web server listen on port 443 or not setting up a virtual server to catch https requests to this port. (On a standard RedHat installation, you shouldn't get this error, as the mod_ssl RPM makes appropriate changes to the Apache configuration.) Check your configuration and documentation. |
| Tomcat not running | Accessing both "https://secure.institution.ac.uk/cas/login" and "http://secure.institution.ac.uk:8080/cas/login" gives a "404 Not found" error | Restart tomcat and check the tomcat log files for error messages. |
| mod_jk not correctly configured | "https://secure.institution.ac.uk/cas/login" gives a "404 Not found" error but it is possible to access "http://secure.institution.ac.uk:8080/cas/login" | Check mod_jk configuration. You must have the "JKMount" directive in the file. You may also have forgotten to restart Tomcat and the web server after making changes. |
The appearance of the CAS login process is determined by a series of JavaServer Pages (JSP) pages. Go to the directory containing these:
# cd $TOMCAT_HOME/webapps/cas
and list the contents to see:
# ls footer.jsp header.jsp login.jsp META-INF success.jsp WEB-INF goService.jsp index.jsp logout.jsp redirect.jsp warnService.jsp
These can be edited to change the appearance. (JSP pages are basically HTML pages with additional tags that allow manipulation of the data presented by the scripts which make up the CAS. The ones that are part of the CAS are not at all complicated and may be edited by anyone with some knowledge of HTML.) Once pages have been edited and saved, the changes should appear immediately.
| File name | Purpose |
|---|---|
| footer.jsp | HTML tags to appear at the bottom of every page returned by the CAS. |
| goService.jsp | This page is presented immediately after login and attempts to redirect the user to the service they requested if there was one. |
| header.jsp | HTML tags to appear at the top of every page returned by the CAS. |
| index.jsp | Redirection of attempts to view this directory from a web browser to the login page. |
| login.jsp | The login form. |
| logout.jsp | Notification that an attempt to logout has been successful, where no service has been selected. |
| redirect.jsp | This page is presented when they move from one service to another to redirect them. |
| success.jsp | Successful login message. |
| warnService.jsp | If a user clicks on the box labelled "Warn me before logging me in to other sites" then this page is presented when the user attempts to move from one service to another. |
Copyright © SECURe Project Team, 2004
Document last updated: 18/03/04