Upgrading Cosign-protected services to version 3.0


This page gives some detail into the ongoing upgrade to Cosign 3.0, as discussed at Operational Meetings. In particular, it describes what you need to do to convert cosign protected sites to using the v3 cosign module. Manual intervention will be necessary, as the v3 module requires the addition of new directives which cause apache to complain if the v2 module is installed. If you have a simple cosigned site, i.e. one with only one host or virtual host, then the changes are likely to be minimal. For these cases, you will probably just need to configure the validation handler (see "Configuration of validation handler" below) and then upgrade to the version 3 module.

Note that when I use the term "client", I'm referring to the cosign module or webserver which is serving cosign-protected content.


The biggest change to the operation of a v3 cosign client is the addition of a url validation handler. This involves the cosign server redirecting to a known location on the client. This is then intercepted by the cosign module which sets the cookie and redirects to the protected page if cookie and destination are valid.

Another change necessitated by version 3 is that different virtual hosts on a machine will no longer be able to use the same cosign servicename.

The newest versions of the cosign component (1.1.31-1 and upwards) provide assistance in configuring these changes, in that they will generate the validation handler configuration fragment and also fragments for configuring additional virtual hosts. Maintainers of cosign-protected sites will be responsible for including these fragments in their httpd configuration. More details below...

Configuration of validation handler

The default location for the validation handler is /cosign/valid, so in almost all cases will be https://hostname/cosign/valid. Apache must be configured so that this location is handled by the cosign module...

The cosign component generates a 'cosign-valid' configuration fragment and puts it in <%cosign.client_serverroot%>/conf.d - this will typically be /etc/httpd/conf.d. For apacheconf configured machines you can include this in your virtual host httpd configuration using something like

!apacheconf.vhostfile_<vhost> mADD(cosign-valid)

(or add it to the apacheconf.configfiles resource to include it at the top level - consult lcfg-apacheconf(8) for details).

Sites using the apache component will need to manually edit their config files, e.g. add the following line to the appropriate part of your config:

Include conf.d/cosign-valid

Configuring a non-standard validation handler location

Some hosts cannot use the standard validation handler location of https://hostname/cosign/valid, e.g. an http host or a host which includes an explicit port number. For these clients you will need to specify the validation handler url manually. This should be done using the cosign.services resource (note that for additional virtual hosts, the macros described below will do this for you). Note that the cosign-valid configuration fragment generated by the cosign component will not work if your validation handler is in a location other than /cosign/valid. For these cases, it is recommended that you copy the cosign-valid fragment that is generated, edit it if necessary, and include it in your configuration.

Configuring the validation

The validation handler also needs to be told which URLs are valid for redirection. You can set this using the cosign.validref resource. This is a regular expression which matches valid service URLs, e.g. the following specifies anything underneath https://hostname.inf.ed.ac.uk/ to be valid:

!cosign.validref  mSET(^https://hostname\.inf\.ed\.ac\.uk(/.*)?)

Note that if you already define the various DICE_OPTIONS_COSIGN_XXX parameters as used in <dice/options/apacheconf-cosign.h>, you can do similar for validref by defining DICE_OPTIONS_COSIGN_VALIDREF, e.g.

#define DICE_OPTIONS_COSIGN_VALIDREF ^https://hostname\.inf\.ed\.ac\.uk(/.*)?

Once you have configured the validation handler, as described above, your host is probably ready for upgrading to the cosign v3 module.

However, if you have more than one virtual host that uses cosign protection, read on....

Configuration of additional virtual hosts

Cosign v3 introduces changes that mean multiple virtual hosts on any one machine can no longer use the same cosign servicename. This means that each virtual host requires its own cosign configuration fragment. The resources needed for configuring cosign for additional virtual hosts are described in lcfg-cosign(8) in the section "CLIENT-SIDE CONFIGURATION FOR ADDITIONAL VIRTUAL HOSTS". These resources specify both the client-side ssl and validation configuration and also the server-side cosign configuration for this service. Users of apacheconf can avoid some of this pain by using a couple of macros provided to set these resources. These are:



... and are documented in <dice/options/apacheconf-cosign.h>

In short, the first requires you to specify in detail the various aspects of client-side cosign configuration, the second is much simpler, but makes a number of assumptions. These macros depend on the x509 component resources service, certfile, keyfile and hashed as configured for the virtual host. They may not work in all cases.

IMPORTANT NOTE: The latest versions of these macros will be shipped as part of the 25/06/09 stable release. You can still use these macros prior to this date, but bear in mind the following: the _APACHECONF_COSIGN_VHOST macro should NOT have a VH argument provided. If you need to specify a non-standard validation handler location, you will need to explicitly use the vhostvhandler_TAG resource AND edit cosign.services to include this.

The new cosign component will also generate httpd configuration fragments (named cosign-client-<vhost>) from these additional vhost resources, putting them in <%cosign.client_serverroot%>/conf.d, as described earlier. These will need to be included in your apache configuration, as also described earlier.

As we now support more than one cosign service per machine, the cosign.services resource has also changed to allow this (this publishes to the spanning map which is used by the cosign servers to allow access to cosign). The apacheconf macros mentioned above will add to cosign.services accordingly. If you set the resources yourself, you will need to change cosign.services yourself. See lcfg-cosign(8) for details.

Installation of cosign v3 module

All you need is this:

!profile.packages          mEXTRA(+cosign-client-apache2-3.0.2-2.inf)

I will, of course, be pushing this out in the cosign headers in due course but, because of the required configuration changes on each host, will not be doing so until all client are suitably configured.

Upgrading example: a simple case

These are the changes I made on scunner (while the services unit weren't looking) to upgrade to v3:

- om apacheconf stop
- rfe lcfg/scunner, added:
!apacheconf.vhostfile_bugzilla mADD(cosign-valid)
!cosign.validref               mSET(^https://bugzilla\.inf\.ed\.ac\.uk(/.*)?)
!profile.packages              mEXTRA(+cosign-client-apache2-3.0.2-2.inf)
- om updaterpms run
- om apacheconf start

If this machine was using the apache module, instead of apacheconf, the only changes above (apart from the obvious name difference) would be to manually include the validation handler (e.g. Include conf.d/cosign-valid) rather than apacheconf doing it for you.

Upgrading example: a more complex case

The host sea presented a bit more of a challenge to upgrade, as not only does it have two virtual hosts, it also has a vhost with a non-standard validation handler url (due to an explicit port number).

This is the LCFG config that was required to upgrade it (I've wrapped lines for readability):

!profile.packages             mEXTRA(+cosign-client-apache2-3.0.2-2.inf)

!apacheconf.vhostfile_pdb     mADD(cosign-valid)
!cosign.validref              mSET(^https://seaproj\.inf\.ed\.ac\.uk:8088(/.*)?)
!cosign.services              mSET(seaproj.inf.ed.ac.uk;0;;Projects_DB_on_sea;

The above lines configure the "first" virtual host for https://seaproj.inf.ed.ac.uk:8088/. The interesting part here is the need for a non-standard validation handler URL, necessitating a change to the cosign.services resource.

_APACHECONF_COSIGN_VHOST(webmk,Webmark - form generation and submission,

!apacheconf.vhostfile_webmk   mREMOVE(cosign-client)
!apacheconf.vhostfile_webmk   mPREPEND(cosign-client-webmk)
!apacheconf.vhostfile_webmk   mADD(cosign-valid)

These lines configure the "second" virtual host, for https://seamark.inf.ed.ac.uk/ using the _APACHECONF_COSIGN_VHOST macro. This generates the cosign-client-webmk configuration fragment. This is added to the configuration using mPREPEND in this instance (rather than mADD) to ensure that cosign is configured before the existing configuration tries to make use of it.

These configurations details would naturally belong in a header file, but this shows how a more complex example can be tested.

Potential Problems

LCFG Spanning map issues

The cosign servers rely on information from the clients which is published to an LCFG spanning map. Unfortunately, due to LCFG limitations, the cosign servers are sometimes not notified of changes. For all cosign-protected services, there should be a line in /etc/cosign.conf on both berlin and osprey. If there isn't, and the client profile has compiled correctly and published the contents of cosign.services to the spanning map, try making trivial changes to both berlin and osprey's profiles.

Redirections, etc.

If you have any httpd configuration that interferes with access to the validation handler location, then this may prevent cosign from working properly. An example of this is something that redirects requests to /cosign/valid somewhere else. This kind of issue will typically result in looping behaviour - where your browser loops between the cosign service and the weblogin servers several times before giving up and complaining with an error.

I solved this for wiki.inf by including the conf.d/cosign-valid after all the existing wiki config. I thought this would be enough, but I had to turn off the Rewriting that the existing wiki config was defining in an earlier <location /> section. So I added:

    <Location /cosign/valid>
      RewriteEngine off
Perhaps that RewriteEngine off could be added to the component generated fragment, perhaps wrapped in a <IfModule mod_rewrite.c> like it does for waklog.


If you have a client that obtains kerberos tickets from the cosign server, there are certain issues which have been exacerbated by version 3. Briefly, if you need tickets, you need to obtain them at the top-level of your host, not in, e.g. a Location block. If you experience problems with this, let me know.

Additional Notes

The LCFG configuration for this isn't very nice, in particular the different ways of specifying client-side configuration for the "first" vhost and for subsequent ones is unpleasant. This is to maintain compatibility with existing configuration as much as is possible. It may all change in the future. Also, the ever-expanding cosign.services resource, for providing information to the cosign server(s), is a nasty piece of work. The next generation LCFG server will no doubt provide nicer ways of doing this.


Email/jabber if you have any questions regarding any of this. I realise there's a lot of information here. I'm happy to lend a hand converting any clients to cosign v3. I'm particularly interested in how people get on with multiple virtual hosts - it's worked for me in testing and I'm keen to see it deployed further.

-- TobyBlake - 08 Jul 2009

-- TobyBlake - 18 Jun 2009

Topic revision: r7 - 11 May 2010 - 14:12:41 - TobyBlake
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