Cosign Frequently Asked Questions
Building, Installation, and Administration
This guide covers downloading, building, configuring, and installing cosign on your web server. For documentation on the weblogin environment at the University of Michigan, please consult their documentation.
- How do I test that cosign is 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
- helloCosign.jsp says "Hello, null!" when I run it.
This is happening because Tomcat is not configured to
use Apache's authentication.
Make sure that your connector description ( ajp13 or
Coyote ) includes the parameter
"tomcatAuthentication=false" if you are using Tomcat
prior to 4.1.18. Otherwise ( or additionally, your
choice ) add the line
"request.tomcatAuthentication=false" to your
jk2.properties file and restart Tomcat.
- After installing mod_cosign.so, Apache gives the error:
Cannot load mod_cosign.so into server: (reason unknown)
The httpd that ships with MacOS X 10.2 ( Apache 1.3.26 )
is compiled in such a way that many third party
modules give this error on load ( just ask google ).
We have not solved the problem yet, but you can work
around it by compiling your module on a previous
version of MacOS X ( it will then load under Jaguar )
or building your own copy of Apache 1.3.26 from source.
- I'm trying to test a new service. It doesn't work and Apache logs something like:
This is a fairly common mod_ssl error and means that your browser has sent an https request over a non-ssl port. Look for a line like: https://servername:80/ elsewhere in the log. Make sure, if 443 is listening and you were just trying to go to https://servername/ that SSLEngine is On & configured.
We've found all browsers behave differently in response to this error. e.g.:
Mozilla: "weblogin.somewhere.edu has sent an incorrect or unexpected message"
Safari: "Could not open the page n.n.n.n because Safari could not establish a secure connection to the server n.n.n.n."
I.E.: displays "pretty" error screen
- I'm having certificate issues, help!
Start by making sure you have your certificate installed correctly,
and that it can be used as an SSL client certificate:
openssl verify -CApath path_to_CAdir -purpose sslclient server.crt
This will only work if the root certificate for the CA that signed
your client's cert is in your CA directory.
- I'm getting vague and unhelpful SSL errors, but my certificate is verified. What else can I do?
There's an openssl tool called "s_client" that will behave like an SSL client. Try these options to help with further debugging. You can then discuss further errors on the cosign-discuss mailing list. Note that you should run the s_client command as the same user the webserver will be running as - typically "www" or some such. Do not run this command as root, as it makes it more difficult to catch permission problems.
openssl s_client -connect cosign-test.example.edu:6663
-showcerts -state -debug
- How do I configure Tomcat 4.1.29 to work with mod_cosign?
To enable Tomcat to see the Cosign-authenticated user from Apache,
it needs a special configuration. 4.1.29 has a new way to do
this, which is really an old way that works again.
you'll want in server.xml: tomcatAuthentication="false"
<!--Define a Coyote/JK2 AJP 1.3 Connector on port 8009-->
port="8009" minProcessors="5" maxProcessors="75"
acceptCount="10" debug="0" connectionTimeout="0"
It no longer needs anything special (or at all) in the jk2.properties file.
How can I convert my X509 cert/key pair into pkcs12 format?
The following openssl command should do the trick:
openssl pkcs12 -in example.cert -inkey example.key \
-export -out excert_key.p12
How do you retrieve the REMOTE_USER value set by
the IIS Cosign filter?
The ISAPI extension
The ISAPI filter
Where can I find more documentation?
What is to prevent Friend email messages from being intercepted and used by someone else?
Not a thing. Friend account creation works pretty much the
same way, you'll notice. These are email-based accounts,
they are as secure as email -- not very. They are designed
to enable collaboration with unaffiliated users, on a casual
basis, where authorization is typically managed directly by the
affiliated user. Don't issue access to sensitive information
to "friends," e.g., information protected by HIPAA, FERPA, etc.
It is possible to have a UMICH.EDU Kerberos principal issued to
people who need more than casual access.
I get an error like this when I build mod_cosign:
usr/bin/ld: ../../common/fbase64.o: relocation
R_X86_64_32S can not be
used when making a shared object; recompile with -fPIC
This is probably because you are on a 64bit machine with a
very recent version of gcc, and as such, you need to build
shared libraries. We'll be rolling a fix into autoconf for
this issue in a future release, but for now just do the
cd libsnet; ./configure --enabled-shared
This will build libsnet as a shared library in addition to
the default, which is static.
You also want to add -fPIC to the DEFS line
I get an error like this when I build cosign:
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. So in csh your configure line will look
env CPPFLAGS=-I/usr/kerberos/include ./configure
and in bash or sh you'd type:
The next release of cosign will detect this issue during
configuration, but the fix remains the same.
How does replication work?
The cosign servers share user data through two mechanisms.
First, there's a "best effort" replication stream. This
causes commands like login, register, and
logout, to be repeated to peer cosign servers. Most
user data thus 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". This 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 spread it's load across all
cosign servers. Thus, multiple cosign servers improves both
resilience and capacity.
After I logout I can still access my Cosign Protected
service for a small window of time. Is Cosign broken?
Cosign is not broken and you have done nothing wrong. You
merely need to customize and make use of the local logout
script provided in scripts/logout. The filters have a cache
time (default 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 one site for a few seconds. To avoid
this, simply call the local logout script which will
re-direct the user to the main logout script.
Can I direct a user to a specific location upon logout?
Simply add a redirect URL to the logout script:
This will override any destination set using
Using CosignHttpOnly on MacOS X Server redirects me to port
16080 - what's up with that?
That's apparently Performance Caching. Turn off the 'Performance
Cache' option in Server Admin for your website.
I want to use Apache's MPM worker. Is that okay?
Version 3.2.0 and prior are not thread-safe. If you use them with any multi-threaded version of Apache, you'll experience random cookie validation failures (and possibly, but unlikely, user impersonation). Wait for a thread-safe version (development is underway, and is likely to be in the 3.3.0 filter).