Bradford Campus Manager

The Raven-related software described on this page is NOT supported or maintained by University Information Services. It is provided here in the hope that it may be useful, but it may contain bugs and security vulnerabilities. It may be supported and maintained by others. You should evaluate whether it meets you particular needs before using it.

This note describes work by the University Computing Service and Bradford Networks in 2010 at the request of Khipu Networks that was intended to allow Bradford Campus Manager (BCM) to authenticate users using Raven. BCM includes support for devolving authentication to an external service, and this has been used successfully in Oxford to devolve user authentication to their Raven analogue. The plan for Raven was closely modelled on the Oxford solution.

Despite significant input from the Computing Service and Bradford Networks this work was not successfully completed. This appeared to be because changes in the latest version of the BCM firmware prevent the Oxford approach from working directly. However the testing did suggest that the Computing Service contributions were doing what they should. Unfortunately the Computing Service, who provided Raven expertise and a test network to experiment on, will be unable to provide any further development resource for his work in the foreseeable future. These notes document the current situation in the hope that someone will be able to take up the work, probably in conjunction with Bradford and Khipu, and turn it into something useful.

Background

When using a BCM, client machines are initially connected to an 'Isolation VLAN' that typically only allows them to contact the BCM itself. While connected to this isolation VLAN, the BCM provides DHCP and DNS services to clients, and the DNS services direct most connections to the BCM - thus when a client tries to browse it is connected to the BCM and can start the authentication process. Once clients have authenticated and complied with any other compliance requirements, the BCM re-connects the client to a public VLAN where it will get 'proper' DNS services and appropriate network access. The BCM itself typically has interfaces to both the isolation and public VLANs. [Note that this summary represents a huge over-simplification of the full features and capabilities of BCM]

To implement external authentication, the BCM is configured to redirect the client's browser to a 'Authentication Helper' web site running on separate hardware. Separate hardware is used to avoid having to integrate third-party authentication code into the BCM itself. The authentication helper is responsible for:

1. Authenticating the user
2. Deciding if they are allowed to use the network, and if they are sending an SNMP trap message to the BCM containing their identity
3. Redirecting the user back to an appropriate URL on the BCM for them to continue the authentication process.

In testing, it appeared that the BCM subsequently needed to connect to a LDAP server on which it could verify the identity returned in the SNMP trap, though it is unclear why this was necessary.

This diagram represents a simple configuration, though for the time being you should ignore the dotted connections:

Implementation - Authentication helper

A small Perl CGI program implements the Authentication Helper function (see ucam-bcm.cgi). It uses the Net::LDAP and Net::SNMP modules (and their dependencies) which must be available.

ucam-bcm.cgi needs a web server to run it. In testing, this was a copy of Apache running on a Linux host, but any appropriate platform (Apache under Windows, IIS, etc.) could be used. ucam-bcm.cgi assumes that the user has already been identified before it runs and that the user's userid is available in the REMOTE_USER CGI variable. In testing this was achieved by protecting ucam-bcm.cgi with Raven and the mod_ucam_webauth Apache module, but other approaches (even ones not involving Raven) could be used providing some sort of user ID appears in REMOTE_USER (or that ucam-bcm.cgi is modified to look in an appropriate place).

The SNMP trap sent to the BCM to authenticate the user uses the client's DHCP-allocated isolation VLAN IP address to identify the client. The server therefore needs to be connected in such a way that it sees connections originating from this address and so it can't be connected via a NAT service. ucam-bcm.cgi expects to find this address in the REMOTE_ADDR CGI variable.

ucam-bcm.cgi is configured by a series of constant declarations towards the top of the program - these should be edited as necessary, though many of the defaults may turn out to be appropriate. See the associated comments for details. Integer values should appear as themselves, strings should be enclosed in single or double quotes. Running the program under Perl with the '-c' command line switch will confirm that no syntax errors have been introduced during editing:

 $ perl -c ucam-bcm.cgi 
 ucam-bcm.cgi syntax OK

By default ucam-bcm.cgi logs copious debug information to STDERR, which should appear in the web server's error log or equivalent. Access to this can be helpful or even is vital while deploying the program. In production debug (though not error) logging can be suppressed by setting the DEBUG constant to 0.

It is possible to execute ucam-bcm.cgi directly on the command line to test it. To do so you should set the REMOTE_USER and REMOTE_ADDR environment variables appropriately. For example (under Unix):

 $ REMOTE_USER=jw35 REMOTE_ADDR=192.168.1.1 ./ucam-bcm.cgi 
 Ucam-BCM: Processing jw35 from 192.168.1.1
 Ucam-BCM: Sending authentication success trap for jw35 on 192.168.1.1 to 192.168.1.3:162
 Ucam-BCM: Trap sent
 Ucam-BCM: Redirecting to 'success' page
 Status: 302 Found
 Location: http://manager.bcm.net.private.cam.ac.uk/registration/common/Cam_CSAPatchNologin.jsp

Note in passing that SNMP traps are sent by UDP with no acknowledgements, so the fact that ucam-bcm.cgi successfully sent a trap is no guarantee that it was successfully received. For that you need debug logging in the trap receiver (the BCM, or for testing something like snmptrapd from the Net-SNMP package).

As shipped, ucam-bcm.cgi will authorise anyone that the web server can authenticate, and so anyone with a Raven account if using mod_ucam_webauth or equivalent. This may not be what's wanted. To address this, it contains optional support for performing an LDAP lookup to decide if network access should be granted for any particular user. This works by sending a query to a configured LDAP server - only if the query returns at least one result is the user allowed network access. If access is denied, then the SNMP trap isn't sent and the user's browser is redirected to a configurable 'failure' page which can explain what happened. This feature is enabled by setting the DO_LDAP_AUTH constant to 1 and setting the other constants starting 'LDAP_'. The default configuration assumes that it will be used against lookup, it but should be sufficiently flexible to be used against almost any LDAP directory. See the comments associated with the various 'LDAP_' constants for more details.

TODO: The SNMP authentication trap sent to BCM (see lines 236-241 of ucam-bcm.cgi) contain various bits of information. There is some confusion over what should be sent in the field identified as 1.3 and at present the place holder value "What goes here?" is sent. This should obviously be replaced with something better. Note that replacing it with the user's real name would involve rewriting the program to do an LDAP lookup every time, not just when DO_LDAP_AUTH is set.

TODO: The SNMP trap is identified as OID 1.3.4.1.4.1.16856 (line 247). This is almost certainly a typo and should probably be 1.3.6.1.4.1.16856. But currently it seems to be what the BCM requires. This might change one day.

TODO: ucam-bcm.cgi's current configuration arrangements (requiring edits to the program) are not ideal. It would obviously be better to use some sort of configuration file and perhaps provide a Web GUI for configuring it. Indeed it might be better to move away from CGI technology to something that doesn't require Perl to be started, the program to be parsed, a configuration file to be read, LDAP connections established, etc. for each separate authentication. That said, the current implementation is almost certainly usable as it stands.

Implementation - Networking

To complete Raven authentication using the Ucam WebAuth protocol the client needs to be able to talk directly to the Raven server (in this respect it may be different for the system in place at Oxford). By default it can't, because the isolation VLAN is typically isolated from the rest of the world. We've identified three ways to address this:

1. Give the machine hosting the authentication helper a second interface and connect this to the public network, make the machine the default router for the isolation VLAN, and have it provide NAT facilities to allow the client to talk across the public network to selected destinations.
2. Connect the isolation VLAN to an institution firewall (assuming that there is one), get it to provides NAT facilities to allow the client to talk across the public network to selected destinations.
3. Implement the isolation VLAN using a VLAN number and IP addresses that are routable across the University network (probably using a 'CUDN-wide private' address range). Implement filtering in a institution firewall or equivalent (e.g. router access lists) to prevent anything on the isolation VLAN from accessing anything other than appropriate selected destinations.

These options are sketched in with dotted lines on the diagram above. In testing we used option 1 and a small shell script (see setup-nat) to set up NAT services.

Note that it is also be necessary to modify BCM's isolation VLAN DNS configuration so that it serves Raven's real IP address in response to requests for 'raven.cam.ac.uk' - by default the BCM is configured to return its own address in response to all requests in order to trigger the authentication service.

Note also that it is important that the web server providing the authentication helper is correctly configured, at least as far as the services offered on the isolation VLAN interface. In particular it must know itself by a name by which clients on the isolation VLAN can access it, because otherwise mod_ucam_webauth will not be able to correctly construct the URL to which the client will be redirected following authentication. If you hit unexpected 'Server not found' or similar errors when trying to access the authentication helper it is likely that this aspect of the configuration is not correct. Setting Apache's 'ServerName' directive would be one way to resolve problems. Firefox's Live HTTP Headers extension (or similar for other browsers) can be a useful tool for tracking redirections to work out where things are going wrong.

TODO: One day the BCM might itself be able to provides NAT facilities to clients on the isolation VLAN, but it can't at present.

In addition to clients needing to access the Raven server, the authentication helper will need to access the configured LDAP server if LDAP-based authorisation is being used (DO_LDAP_AUTH set to 1). It should be able to do this using the same facilities used by the clients, though it will need permission to do so. If relying on the BCM's DNS to locate the LDAP server then the BCM will additionally need to to be configured to return the real IP address for the LDAP server.

Implementation - directory

During testing it appeared that the BCM itself needs to do a lookup against an LDAP directory of the identity returned in the SNMP trap (this is entirely separate from ucam-bcm's ability to do LDAP-based authorisation). It is not entirely clear why it needs this. This can be against a suitable local LDAP server, but it can also be against lookup. Unfortunately BCM's idea of how an LDAP server should work and the way that lookup actually works are not well aligned. In particular:

1. lookup expects most lookups to be performed anonymously but BCM insists on authenticating. This can be worked around because lookup supports the idea of authenticating as a group - this is intended for gaining to privileged group membership information but also gives access to the information normally available anonymously. To take advantage of this, have someone in the 'Management Group' for your institution create a group and go to the group's edit page and click the 'Generate a password' button. You should then be able to authenticate using the DN

    groupID=<group-id>,ou=groups,o=University of Cambridge,dc=cam,dc=ac,dc=uk

(where <group-id> is the numeric identifier of the group in question), and password generated above.

2. lookup will only allow authentication over encrypted connections, which means SSL or TLS. To configure this it appears to be necessary to supply the BCM with a copy of the certificate used by the LDAP server. This seems to be a very bad idea since it will cause problems whan the certificate or keys on the LDAP server are renewed as part of normal operation. If you are using lookup, the easiest way to obtain a copy of the necessary certificate is to collect it from the LDAP server itself:

    openssl s_client -connect ldap.lookup.cam.ac.uk:ldaps -showcerts

and then hit Ctrl-D to close the connection this opens. This will display the various certificates used by the connection. The one you want is the first. Having collected it you should verify that it is indeed for the right host (ldap.lookup.cam.ac.uk in lookup's case) and has been correctly signed by a trusted Certification Authority. Doing this is left as an exercise for someone who understands SSL.

An alternative solution might be to create some sort of SSL-to-SSL proxy which connects to lookup using normal CA-based certificate validation, and which BCM connects to using a locally-issued, long-validity certificate which can then be loaded into the BCM. Again, doing this is left as an exercise for the reader. ... One reader has come up with this:

  socat OPENSSL-LISTEN:636,reuse-addr,fork,cert=foo.pem,cafile=bar.pem OPENSSL:ldap.ref.com:636,cert=real.pem,cafile=otherca.pem

This is untested, but should provide the basis for a solution which just Man In The Middle's a connection to Lookup, but means that you don't need to worry about the certificate changing at an unexpected time.

General

TODO: Currently, deploying all this requires configuration changes on the BCM that are not detailed here and so assistance from Bradford or Khipu is currently required for deployment. Clearly the situation would be improved were this sort of deployment to become a documented, supported task that could be completed entirely through the BCM GUI.

TODO: Setting all this up requires a wide mix of skills that may not be available to all potential users. Unfortunately many details will depend on local circumstances, making 'recipe'-style instructions difficult or impossible to provide. Ideally the entire authentication helper application would be made into some sort of 'Appliance' like the BCM (apparently in Oxford OUCS distribute an virtual machine image), together with a web-based configuration GUI. At present there is no prospect of the Computing Service having the resources available to do this.

Jon Warbrick
June 2010