TWiki> DICE Web>CosignClient (revision 4)EditAttach

Using Cosign with Apache

This page provides instructions on using the Informatics Cosign servers to protect Apache websites running on DICE machines.

Cosign Overview

Cosign is a single sign-on (SSO) web login technology developed at the University of Michigan. It uses a centralised sign-on mechanism to authenticate users (for Informatics users, this means authenticating with your Kerberos principal). It uses login and service cookies to manage the authorization for a cosign-protected web site. More information on how Cosign works can be found on the Cosign web site

Note that all Cosign communication between machines is SSL-protected.

It is planned that Cosign will eventually replace KX509 for all Kerberised web site authorization within Informatics.

LCFG Configuration

The first step in Cosign-protecting your web site is to add the following header to the machine's profile

#include <dice/options/cosign-client.h>

Once the profile has compiled, run om updaterpms run to install the cosign software on your machine. This software consists of the cosign component and the client-side cosign filter itself, which is implemented as an Apache module (for both Apache 1 and Apache 2). You should start the component at this point with om cosign start.

The cosign client needs to know which user the web server is running as, primarily so it can make files and directories readable. This currently defaults to apache. To change this, set the following resources to the appropriate user and group:

!cosign.user                    mSET(apache)
!                   mSET(apache)

Next, your Cosign service needs a service name - email the infrastructure unit to request one of these - it needs to be unique. Once you have this, you should set the following resource to the appropriate value:

cosign.servicename              mSET(myservicename)

The cosign servers maintain a dynamically-generated services list, which determines which machines can connect to them. To add your web server to this, add the service details to, e.g.:

! mADD(;0;;Test_Client_on_hostname;

See the man page for lcfg-cosign(8) for more details on what these fields are.

Note that any underscores in the 4th field will be replaced by spaces in the automatically generated services web page.

SSL Certificates

You will need to configure the SSL certificates for a cosign-protected web site. If this is an existing https web server which is being converted to using cosign, then you will already have certificates installed. If not, the x509 component can be used to generate signed certificates for Informatics servers. The man page for lcfg-x509 gives further details on how to do this. As an example, the following resources...

!x509.hashed_hostname             mSET(/etc/httpd/conf/CA)

... would lead to hostname.[chain|crt|key] being created in /etc/httpd/conf with hash files for each certificate in the chain file being created in /etc/httpd/conf/CA (the Cosign filter requires these).

Unfortunately, the x509 component doesn't work quite as well as it should do, in particular it won't create hash files for an already existing certificate and it also requires that the directory for the hash files is already in existence. You can generate the hash files manually, but it's probably easier to force the x509 component to regenerate the certificates completely. To do this:

  • Move the existing .crt file out of the way (i.e. in the example above, move the file /etc/httpd/conf/hostname.crt).
  • Create the CA directory (i.e. in the example above, create the dir /etc/httpd/conf/CA with username and group permissions that allow it to be read by the webserver.
  • om x509 run should cause the certificates to be newly generated.

The cosign filter needs to know where to find these certificates and this is done by setting the following resources:

cosign.file_filter_key          /etc/httpd/conf/hostname.key
cosign.file_filter_crt          /etc/httpd/conf/hostname.crt
cosign.path_filter_ca           /etc/httpd/conf/CA

Complete LCFG Configuration

Putting all of this together for an example service running on would lead to resources similar to the following being added to the machine's profile:

#include <dice/options/cosign-client.h>

cosign.servicename              myservicename

/* most existing web servers will already have their own certs
    so won't require the _X509_SERVICE line                    */

!x509.hashed_hostname            mSET(/etc/httpd/conf/CA)

cosign.file_filter_key          /etc/httpd/conf/hostname.key
cosign.file_filter_crt          /etc/httpd/conf/hostname.crt
cosign.path_filter_ca           /etc/httpd/conf/CA

! mADD(;0;;Test_Client_on_hostname;

Apache Configuration

The cosign component will generate a section of an httpd.conf file, which will need to be incorporated into the httpd.conf file used by the web server.

The resources for the example above would lead to the following /var/cosign/filter-httpd-sample.conf file being created:

# This is an automatically generated section of an apache httpd.conf,
# to be used by a cosign-enabled web-service.
# You will need to edit the text below before including it in your
# apache config (at the very least to fill in the Location and
# uncomment the filter appropriate to the apache version you're
# running).
# You should also ensure that the certificate files used by the cosign
# filter are readable by the user the web server is running as

# Pick the appropriate cosign module below for either apache1 or
# apache2
# Apache1:
# LoadModule cosign_module /usr/lib/apache/
# Apache2:
# LoadModule cosign_module /usr/lib/httpd/modules/

CosignProtected Off
<Location /FILL-IN/>
  CosignProtected On
  CosignService myservicename
  CosignCrypto /etc/httpd/conf/hostname.key /etc/httpd/conf/hostname.crt /etc/httpd/conf/CA
  AuthType Cosign
  Require valid-user

You will need to edit this configuration, as detailed in the comments, before including the relevant parts in the web server's httpd.conf file. Once this is done, you should restart apache.

If all has gone according to plan, visiting the cosign-protected service ( in the example above) will re-direct you to the cosign server ( and ask you to authenticate (for DICE users using Firefox and with existing kerberos credentials, this part will happen automatically)

-- TobyBlake - 26 Jul 2007

Using Apacheconf

Apacheconf is a new component for configuring Apache which supports modular service construction, allowing the simple configuration of multiple services on the same machine. It also offers mechanisms for simply configuring cosign at the LCFG level. A full overview of Apacheconf can be found in it's man page, however here are some pointers in using it to configure a cosign protected service...

Firstly, you need to obtain an X509 certificate for your service. Even if your service isn't TLS protected, you need a certificate to allow you to communicate with the cosignd. In addition to obtaining the certificate, you need to ensure that it is readable by the user your webserver runs as, and has the hashed datastructure required by cosign.

#include                          <dice/options/x509-client.h>
!x509.certificates                mADD(servicename)
!x509.hashed_hostname             mSET(/etc/pki/tls/certs/servicename.CAs)
!x509.uid_hostname                mSET(<%apacheconf.user%>)
!x509.gid_hostname                mSET(<>)

Then, you need to setup the Apacheconf component. Firstly pick whether you want an Apache-1.3 (deprecated) or Apache-2.0 based service, and include apacheconf-13.h or apacheconf-20.h as appropriate. Then, set it up as an SSL service (if appropriate), and as a cosign protected one.

#include                          <dice/options/apacheconf-13.h>

#include                          <dice/options/apacheconf-ssl.h>

#define DICE_OPTIONS_COSIGN_X509TAG hostname
#include                          <dice/options/apacheconf-cosign.h>

myusername and mygroupname should be the username and groupname that you want the Apache server to run as. hostname is the same as you set in the X509 definitions earlier, and allows cosign to find your certificates. DICE_OPTIONS_COSIGN_DESCRIPTION is set to the description of the service you want to appear in the cosign service list, and must not include spaces.

The apacheconf-cosign header takes other options, which are documented at the begining of that header file.

Then, you must set up your virtual host, in the same way as for any other apacheconf governed service

!apacheconf.vhosts                mADD(myservice)
!apacheconf.vhostname_myserv      mSET(servicename)
!apacheconf.vhostport_myserv      mSET(443)
!apacheconf.vhostssl_myserv       mSET(yes)
!apacheconf.vhostsslcert_myserv   mSET(<%x509.certfile_hostname%>)
!apacheconf.vhostsslkey_myserv    mSET(<%x509.keyfile_hostname%>)
!apacheconf.vhostsslchain_myserv  mSET(<%x509.chainfile_hostname%>)
!apacheconf.vhostfile_nagios      mSET(cosign-client cosign-vhost-all)
!apacheconf.vhostfile_nagios      mADD(myservice.conf)

The above sets up an SSL Virtual Host for servicename. Including the configuration file cosign-client sets up all of the cosign settings for that host. Including cosign-vhost-all protects all locations on that virtual host with cosign. Finally, myservice.conf is included to incorporate any service specific configuration.

-- SimonWilkinson - 27 Aug 2007

Edit | Attach | Print version | History: r11 | r6 < r5 < r4 < r3 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r4 - 27 Aug 2007 - 10:48:58 - SimonWilkinson
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies