Cosign Web SSO daemon, CGI, Apache filters and Lighttpd filter
C Shell JavaScript CSS Perl PHP
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
cgi Preliminary patch for request #13: allow custom friend DB name Jan 14, 2014
common correct undef typo Feb 22, 2014
daemon Preliminary patch for request #13: allow custom friend DB name Jan 14, 2014
filters apache2: Apache 2.4 support. Oct 12, 2013
helloCosign moving helloCosign around. May 3, 2006
html Add "server" and "install-server" Makefile targets. Add DESTDIR support. Nov 29, 2011
libcgi Free cgi in error handling if malloc of cgi->ci_buf fails. Feb 25, 2012
libsnet Add --enable-universal-binaries. Jan 16, 2009
scripts Substitute correct build-time path prefix into startup scripts. Apr 3, 2012
tests "make test" updates: bump key bits to 2048, fix CRL path Jan 7, 2014
.gitignore Ignore config.h generated by autoheader. Aug 20, 2009
CHANGELOG Changes from 3.1.4 through 3.2.0rc2 Feb 4, 2012
Contributors New contributors. Jan 26, 2009
EXCLUDE Correct tar exclude pattern for .git directory. Apr 3, 2012
LICENSE updated documentation to 1.5.x changes, added new images files Apr 9, 2004 Substitute correct build-time path prefix into startup scripts. Apr 3, 2012
NOTES preserve krbtktpath post ip change. Jun 23, 2006
README Updated for cosign3. Apr 8, 2009
README.basicauth Updated for cosign3. Apr 8, 2009
README.weblogin Updated for cosign3. Apr 8, 2009
VERSION internal Apr 8, 2003
aclocal.m4 apache2: Apache 2.4 support. Oct 12, 2013
config.guess new config.[sub|guess], loop url config-able, CosignProtected allowed in Mar 18, 2005
config.sub new config.[sub|guess], loop url config-able, CosignProtected allowed in Mar 18, 2005 Preliminary patch for request #13: allow custom friend DB name Jan 14, 2014
install-sh autoconf, baby! Oct 15, 2002 build update Dec 5, 2007


These instructions are for building the Apache authentication filter.
If you need to set up an entire weblogin infrastructure please see
README.weblogin (for sites using Kerberos) or README.basicauth for any
other AuthN backend.

Before you begin:

    For documentation and information see:

    To build a production Apache filter you need Apache 1.3.X or Apache
    2.x.  If you happen to use the Apache 2.x filter in production,
    please let us know about it. Your web server should have SSL enabled.

    You will need OpenSSL 0.9.7a or newer.

    You will need a source of entropy for the OpenSSL libraries to work.
    If your system has /dev/*random then you're all set, otherwise you
    should get something like prngd or egd.  Solaris users should refer
    to document 27606 "Differing /dev/random support requirements within
    Solaris [TM] Operating Environments" at <>.
    AIX users will want to get prngd.

    If your cosign protected service needs kerberos credentials, you
    will need MIT krb5-1.2.7 or later.  Kerberos libraries are not
    required if you do not need access to kerberos credentials.  If you
    are building a central weblogin server, see README.weblogin.

To build the Apache authentication filter:

    NOTE: On Redhat 9, kerberos is in a  non-standard place, and so, by
    default, configure may not find it. So if you need to use kerberos
    ticket transfers, you will need to do the following.

    Add "env CPPFLAGS=-I/usr/kerberos/include" before you run configure.
    So in csh your configure line will look  like this:

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

    and in bash or sh you'd type:

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

To build:

    ./configure --enable-apache1=/path/to/apache1/apxs
    ./configure --enable-apache2=/path/to/apache2/apxs
    make install
    mkdir -p /var/cosign/filter
    chown APACHE_USER /var/cosign/filter

    'make install' will install the filter using your copy of apxs.  Be
    sure to change APACHE_USER to the username defined in your
    httpd.conf file.

    Users requiring kerberos tickets for their cosign-protected services
    will want to add --enable-krb to the ./configure command line. GSSAPI
    support in the filter can be added with --with-gss.

    Mac OS X web administrators will likely want to include an additional
    option to the ./configure command line, --enable-universal-binaries.
    This option ensures that the resulting filter contains support for
    four architectures, and will load with the version of Apache 2.x
    included with recent versions of Mac OS X.

Configure Apache ( U of M specific example ):

    If you need a certificate, we can provide one signed by the umweb CA at
    no cost. Self-signed certs will not work wih Cosign. You may also
    purchase a commercial certificate. Please visit the Web Application
    Sign-Up page at for more info.

    NOTE: When filling out the CSR, you will be prompted for the CN. It
    says "Common Name (eg, YOUR name) []:" - despite what the prompt
    says, you should type in the hostname of your webserver, eg
    "". Additionally, the state field should
    read "Michigan" and not "MI".

    In the U of M environment, you'll want your directives to look like

    On your http ( port 80 ) side, and any dirs or locations you want

	CosignProtected		Off

    in :443 ( or otherwise https ) vhost

    CosignProtected		On
    CosignService		<e-mail to and we will assign>
    CosignCrypto		/path/to/key /path/to/cert /path/to/CAdir
    CosignValidReference	^https?:\/\/.*\.umich\.edu(/.*)?
    <Location /cosign/valid>
	SetHandler	cosign
	CosignProtected	Off
	Allow from all
	Satisfy any

    NOTE: trailing slash is required on CosignRedirect! The redirects
    won't work correctly without it.

    ANOTHER NOTE: most mod_cosign options can be configured on a
    per-directory basis. In order to have this flexibility, the
    server-wide configurations must be listed "first" in the httpd.conf
    file, before any per-directory configuration options.

Stop and Start Apache

See README.scripts for a cron job that prunes old cookies from the
filter's database and scripts for local logout.

Apache Configuration Options:

	CosignProtected		[ on | off ]
	    governs whether Cosign is invoked or not

	CosignHostname		[ the name of the host running cosignd ]
	CosignValidReference	[ a regular expression matching valid
				service URLs. After the user logs into
				a service, they are redirected to the
				validation URL (e.g.,,
				where mod_cosign checks the user's cookie
				and compares the service URL to the value
				set by CosignValidReference. If the cookie
				and service URL are good, mod_cosign
				redirects to the service URL. ]
	CosignValidationErrorRedirect	[ the URL to redirect to if the
					validation handler URL cannot
					validate the service cookie or the
					service URL. ]
	CosignRedirect		[ the URL of the cosign login cgi ]
	CosignPostErrorRedirect	[ the URL to redirect to if the user
				would be redirected to the login cgi
				during a POST. This screen lets people
				know we dropped their data. ]
	CosignService		[ the name of the cosign service cookie ]
	CosignSiteEntry		[ the URL to redirect to after login  ]
	CosignCrypto		[path to key] [path to cert] [path to CA dir]
	CosignRequireFactor	[ a list of the factors a user must satisfy ]
	CosignFactorSuffix	[ optional factor suffix when testing
				for compliance ]
	CosignFactorSuffixIgnore	 [ on | off ]
	CosignHttpOnly		[ on | off ]
		module can be use without SSL - not recommended!
	CosignTicketPrefix	[ the path to the Kerberos ticket store ]
	CosignFilterDB		[ the path to the cosign filter DB]
	CosignFilterHashLength	[ 0 | 1 | 2 ]
	    subdir hash for cosign filter DB
	CosignCheckIP           [ never | initial | always ]
	    check browser's IP against cosignd's ip information
	CosignProxyDB		[ the path to the cosign proxy DB]
	CosignAllowPublicAccess		[ on | off ]
	    make authentication optional for protected sites
	CosignGetKerberosTickets	[ on | off ]
	    module asks for tgt from cosignd
	CosignKerberosSetupGSS		[ on | off ]
	    setup the enviornment so that other apache modules
	    that need GSSAPI/Kerberos work. e.g. IMP running under mod_php
	CosignGetProxyCookies	[ on | off ]
	    module asks for proxy cookies from cosignd

	Cosign 3.0 introduces the validation handler URL for services,
	allowing services to be more restrictive about redirections and
	cookies within the cosign environment. Apache must be configured
	to set mod_cosign as the handler for a special URI. Consult your
	weblogin administrators for the correct settings in your own
	environment. This Location block will generally be enough for
	your cosign 3.0 service:

	    <Location /cosign/valid>
		SetHandler	cosign
		CosignProtected	Off
		Allow from any
		Satisfy all

	NOTE: a Location block for '/' in which CosignProtected is set to
	On will override the /cosign/valid Location block. If you need to
	cosign-protect the document root, set CosignProtected to On in the
	virtual host context, not in the <Location /> block.

The certificate CN of the weblogin server must match CosignHostname.

./configure may take the following options:

    --enable-krb=path_to_krb5		enables Kerberos V
    --enable-apache1=path_to_apxs_1.3	enables Apache 1.3 filter
    --enable-apache2=path_to_apxs_2	enables Apache 2 filter
    --enable-universal-binaries		build universal binaries (Mac OS X)
    --with-GSS				enables GSSAPI
    --with-filterdb=DIR         	overrides default of /var/cosign/filter

To make Cosign work with Apache's require directives, you should do the

In httpd.conf, for the directory structure you want to Cosign Protect
and use apache's require directives on, add the following line:

    #this examples turn this on for everything
    <Directory />
	AllowOverride AuthConfig Limit

This will allow you to use .htaccess files for Authorization. So now you
can do something like this:

    AuthType Cosign
    require user wes canna clunis jarod

This will make it so the core cosign development team can view the pages
in this hypothetical directory. For more info on this, see Apache's docs
on .htaccess.

Alternatively you can just specify authorization information inline in

    <Directory />
	AuthType Cosign
	Require user grouch harpo chico

This allows the marx brothers to exclude Zeppo ( and anyone else ) from
accessing content on their webserver.