README.basicauth

Before you begin:

    Starting with Cosign 2.0, you can use any arbitrary external
    authenticator as the authentication back end for cosign. The
    cosign.conf(5) man page has more details.

    Implementing an external authenticator is prefereable because it
    allows for a full featured user interface with good opportunities
    for feedback and interaction.
    
    These instructions are for people who want to leverage Apache based
    authentication methods to bring up cosign.
    
    For documentation and information see: http://weblogin.org/

    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 <http://sunsolve.sun.com/>.  AIX users will want to get
    prngd.


To build the central cosign server ( the weblogin server ):
    Note that you should only need this if you are establishing a new
    SSO community for which you will be providing the central login
    server.

	./configure --enable-apache1=/path/to/apache1/apxs
	    OR
	./configure --enable-apache2=/path/to/apache2/apxs
	make everything
	make install-all
	mkdir -p /var/cosign/daemon
	chown DAEMON_USER /var/cosign/daemon
    
    The daemon (cosignd) requires  /var/cosign/daemon to exist and be
    writeable by the user the daemon runs as, by default "cosign".

Testing your certificates:

    You want to make sure that the certs you have are able to be used as
    both a server ( weblogin server ) and a client ( cosign.cgi ). Debugging
    certificate problems is the hardest thing to do, and checking now saves
    a lot of anguish later.

	openssl verify -verbose -purpose sslclient -CApath /var/cosign/certs/CA /var/cosign/certs/cert.pem

	openssl verify -verbose -purpose sslserver -CApath /var/cosign/certs/CA /var/cosign/certs/cert.pem

Configuring your server:
    You'll want something like the following

	#this is so the login will run from / of DocRoot
	DirectoryIndex      cosign.cgi index.html 
	AddHandler          cgi-script      .cgi
	<Directory /path/to/docroot>
	    Options ExecCGI
	</Directory>

	#so anything they ask for will take them to the authentication script
	ErrorDocument       404     https://cosign.example.com/

    Otherwise configure your server in the regular way you would to
    make the type of BasicAuth you want to use work in your environment.

    The BasicAuth flavor of cosign.cgi checks that REMOTE_USER has
    already been set by BasicAuth and take the appropriate
    login/register actions.

Customizing your html:

    We provide an example login screen and other templates which you are
    welcome to use but you'll probably want to customize. Be careful
    with the variable display strings ( of the form '$a' where 'a' can
    be any letter or number ).  These are needed by the CGI. See the
    comprehensive cosign scheme document at http://weblogin.org for
    details on the templates and variable substitutions required by the
    CGI.

Things to know about the CGI:

    The required html and templates for the cgi ( login page, logout
    page, services page, looping page etc. ) live in ${prefix}/html and
    ${prefix}/templates. You will most likely want to localize these
    pages.

Creating cosign.conf file:

    The last thing you need to do before starting up your cosign server
    is create the cosign.conf file. Please see cosign.conf(5) for
    details.

Scripts

    See the scripts/ directory in the cosign source distribution for an
    example cosignd startup script, a cron job to clean up your cookie
    database (if you are not using replication), and several example
    logout scripts. There are also scripts provided to create and
    convert the directories in the cosign database if you choose to use
    directory hashing. Finally, there is an example of an external
    authenticator script located in the factors sub-directory.

./configure options:

    --with-cosignhost=NAME  	default=cosign.example.edu
    --with-cosignlogouturl=URL	default=http://cosign.example.edu
    --with-cosignloopurl=URL	default=http://cosign.example.edu/looping.html
    --with-cosigndb=DIR 	overrides /var/cosign/daemon
    --with-cosignconf=FILE	specify new conf file location
    --with-cosigncadir=DIR	default=/var/cosign/certs/CA 
    --with-cosigncert=FILE	default=/var/cosign/certs/cert.pem
    --with-cosignkey=FILE	default=/var/cosign/certs/key.pem
    #these next 2 are not necessary for BasicAuth
    --with-ticketcache=DIR	default=/ticket
    --with-keytabpath=FILE 	default=NULL ( which means use whatever
					the krb5.conf says to use )
    --enable-mysql=path_to_mysql
                      enable mysql for guest login support in the cgi
    --with-frienddbhost=NAME
                            default=localhost
    --with-frienddblogin=NAME
                            default=friend
    --with-frienddbpasswd=PASSWD
                            no default

    The certificate CN of the weblogin server must match the argument
    to --with-cosignhost.

    Rate Logging:

        Starting with 1.7, we've simplified the logging paradigm. There's
	a file in common/ called rate.h and a #define of RATE_INTERVAL.
        This means that every RATE_INTERVAL number of events, cosignd
        will write out a summary log line that shows the rate for that
        particular event. For example, for the CHECK command you'd see:

            STATS CHECK 141.211.144.17: UNKNOWN .0012 / sec
            STATS CHECK 141.211.144.17: PASS 1.2 / sec

        and that would indicate that the rate of 5xx ( or unknowns )
        returned to that host was .0012 per second and the rate of 2xx
        ( or pass ) was 1.2 per second. More information follows in
        the cosignd(8) and monster(8) man pages.

Questions? cosign@umich.edu