From cosign wiki

Revision as of 22:42, 20 February 2008

Cosign Frequently Asked Questions

This FAQ covers topics on building, configuring, and installing Cosign on your web server, as well as miscellaneous Cosign-related topics that don't fit anywhere else.

Building Cosign

• Building mod_cosign on a 64-bit machine results in an error similar to the following:

usr/bin/ld: ../../common/fbase64.o: relocation R_X86_64_32S can not be used when making 
a shared object; recompile with -fPIC

64-bit machines with recent versions of gcc require custom shared libraries. Until this is addressed in a future release, the following command builds libsnet as a shared library in addition to the default, static library:

cd libsnet; ./configure --enable-shared

In addition, add -fPIC to the DEFS line in cosign/common/Makefile.

• Building mod_cosign results in an error similar to one of the following:

from snet.c:22: /usr/include/openssl/kssl.h:72:18: krb5.h: No such file or directory

configure: error: header file <openssl/ssl.h> is required for this software. You may be running RedHat 9.

You are likely running Redhat 9, or an implementation of SSL that expects Kerberos. On Redhat 9, Kerberos is in a non-standard place, and so, by default, configure may not find it. Add env CPPFLAGS=-I/usr/kerberos/include before you run configure. In csh, your configure line would look like the following:

env CPPFLAGS=-I/usr/kerberos/include ./configure

In bash or sh, your configure line would look like the following:

CPPFLAGS=-I/usr/kerberos/include ./configure

Future Cosign releases will detect this issue during configuration, but the fix will remain the same.

Installation

• How do I verify that Cosign is properly installed and running?

  See the scripts/hello directory in your Cosign distribution. This directory includes helloCosign scripts and programs in various programming languages. Install one of these in your web server's document root to verify that the REMOTE_USER environment variable is being properly set and made available to your deployment environment.
  

• After installing mod_cosign.so, Apache gives an error: Cannot load mod_cosign.so into server: (reason unknown)

  The httpd that ships with MacOS X 10.2 (Apache v1.3.26) is compiled in such a way that many third-party modules (including Google's) give this error on load. This problem has not yet been solved, but you can work around it by compiling your module on a previous version of MacOS X, which will then load under Jaguar, or by building your own copy of Apache v1.3.26 from source.
  

• A new test service doesn't work and creates Apache log entries like \x80g\x01\x03 or x80g\x01\x03\x01.

  This common mod_ssl error indicates that a browser has sent an https request over a non-SSL port. Check the log for entries that include attempts to connect to hybrid SSL/non-SSL hosts, such as https://server_name:80. In addition, ensure that the server is listening on port 443, and that SSLEngine on the server is set to on and is properly configured.
  

  Different browsers behave differently in response to this error:

  * Mozilla displays an error such as "server_name has sent an incorrect or unexpected message."

  * Safari displays a similar error: "Could not open the page page_name because Safari could not establish a secure connection to the server server_name."

  * Internet Explorer displays a "pretty" error screen.
  
  

Configuration

• When I run helloCosign.jsp, it says "Hello, null!"

  This occurs when Tomcat is not properly configured for using Apache authentication.
  

  Ensure that your connector description (e.g., ajp13 or Coyote) includes the parameter tomcatAuthentication=false if you are using Tomcat prior to version 4.1.18. Otherwise (or additionally, your choice) add the line request.tomcatAuthentication=false to your jk2.properties file and restart Tomcat.
  

• Can Cosign use certificates issued by Entrust?

  Until recently, Entrust only signed certificates to be used on SSL servers. (Entrust "Advantage" certificates now support SSL client functionality). Only SSL Clients enable mod_cosign talk to cosignd. You verify whether a certificate can be used as an SSL Client with the following command:
  

  openssl verify -CApath path_to_CAdir -purpose sslclient server.crt

  This will only work if the CA that signed your client's certificate is in your CA directory. The Cosign distribution comes with the CAs for Entrust, Verisign, and umweb.

• My certificate is verified, but I'm still getting vague and unhelpful SSL errors. What else can I do?

  s_client, an OpenSSL tool, behaves like an SSL client and can aid in debugging SSL errors. You can use s_client results to discuss errors on the cosign-discuss@umich.edu mailing list. Note that you should run the s_client command as the same user as the webserver, typically www. Do not run this command as root, as doing so makes it difficult to catch permission problems.
  

  Try a s_client command with syntax similar to the following:

openssl s_client -connect cosign-test.example.edu:6663 -cert \
 /etc/apache/certs/cosign-test.cert -key /etc/apache/certs/cosign-test.key -CApath \
 /var/cosign/certs/CA -showcerts -state -debug -crlf -starttls smtp

• Can I run mod_UMICH_authcookie and mod_cosign on the same machine?

  No, as they conflict with one another. In order to run mod_cosign, comment out the LoadModule block that loads mod_UMICH_authcookie, or better yet: remove it altogether. Also comment out any directives associated with mod_UMICH_authcookie, or ensure that they are contained in IfModule blocks.

• How do I configure Tomcat v4.1.29 to work with mod_cosign?

  Enabling Tomcat to see Cosign-authenticated users from Apache requires the parameter tomcatAuthentication="false" in server.xml, as in the folowing example:

<!--Define a Coyote/JK2 AJP 1.3 Connector on port 8009-->
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
	port="8009" minProcessors="5" maxProcessors="75"
	enableLookups="true" redirectPort="8443"
	acceptCount="10" debug="0" connectionTimeout="0"
	useURIValidationHack="false" tomcatAuthentication="false"
	protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler"/>

No special configuration is required to the jk2.properties file.

• Why can users access Cosign-protected service during a small window of time after logging out?

  The filters have a cache time, which defaults to 2 minutes, during which they will not validate a user's status. As such, when a user returns post-logout, the cache is still valid and the user is still "logged in" to that site for a few seconds. To avoid this, simply call the local logout script, provided in scripts/logout, which will re-direct the user to the main logout script.

• Can I redirect a user to a specific location upon logout?

  Simply add a redirect URL to the logout script:

/cgi-bin/logout?http://www.anotherlocation.com

This will override any destination set using --with-cosignlogouturl.

• Why does CosignHttpOnly on MacOS X Server redirect to port 16080?

  This is a result of MacOS X Server's Performance Caching option, which can be turned off in your website's Server Admin.

Miscellaneous

• How do I convert an X.509 cert/key pair to pkcs12 format?

  Use the following OpenSSL command:

openssl pkcs12 -in example.cert -inkey example.key \
    -export -out excert_key.p12

• How do I retrieve the value of HTTP_REMOTE_USER set by an IIS Cosign filter?

  Use the ISAPI extension GetServerVariable() function, or the ISAPI filter GetHeader() function.

• What prevents Cosign Friend email messages from being intercepted and used by someone else?

  Nothing. In fact, Friend account creation works very much in the same way. As these are email-based accounts, they are only as secure as email itself. They are designed to enable collaboration between unaffiliated users on a casual basis, where authorization is typically managed directly by the affiliated user. Don't issue "Friends" access to sensitive information, e.g., information protected by HIPAA, FERPA, etc. Request a UMICH.EDU Kerberos principal for people who need more than casual access.

• How does replication work?

  Cosign servers share user data via two mechanisms:

  • First, there's a "best effort" replication stream, which causes commands like login, register, and logout to be repeated to peer cosign servers. Thus, most user data exists on all available Cosign servers.
  • Second, monster propagates both last-check times and the logged-out state between servers. This makes dropping the logout during replication less of a problem. The logout.cgi also sets the login cookie to "null", which is another source of logout resilience.

Because of the possible delay between checks and the propagation of last-check times, the server will respond with a 5xx response for a few minutes after the user has apparently timed out. Clients interpret 5xx to mean, effectively, "I don't know; ask someone else". If all servers respond with 5xx, the filter will consider the user to be logged out.

The goal for the filter is to balance its load across all Cosign servers. Thus, multiple Cosign servers improve both resilience and capacity.

• Is Cosign the same thing as CookieServer or DonutD?

  Cosign inherits a number of ideas from both of these systems, but it is not a direct descendant of either. The University of Michigan first deployed a WebISO system called CookieServer in late 1995 to provide web authentication for the "Wolverine Access" student records and registration system. Circa 1999, a piece of software called DonutD was grafted onto CookieServer to provide a campus portal system with Kerberos credentials on behalf of the authenticated user. The developers of Cosign learned a great deal from maintaining, administering, and using these systems in production, and they have used this knowledge in building Cosign.

• Where can I find more information?
  • Apache Filter README file
  • BasicAuth CGI and server README file
  • Cosign Kereberos CGI and server README file
  • Support scripts README file

--John DeStefano 15:43, 15 November 2006 (EST)