Bradford Campus Manager
This note describes work by the University Computing Service and Bradford Networks in 20101 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 analog. 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, are 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 get this to work.
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 (see diagram, though for the time being ignore the dotted connections). [Note that this summary represents a huge 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:
- authenticating the user,
- deciding if they are allowed to authenticate, and if they are sending an SMTP trap message to the BCM containing their identity, and
- 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.
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 identity 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 the user's identity 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 is vital while deploying the program. Debug 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
As shipped, ucam-bcm.cgi will authenticate 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 authentication for any particular user should be allowed. This works by sending a query to a configured LDAP server - only if the query returns at least one result is the user allowed to authenticate. If the user isn't allowed to authenticate 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 placeholder 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.
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:
- Give the machine hosting the authentication helper a second interface, connect it to the public network, make it 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.
- 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.
- 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 setup NAT services.
Note that it will 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 'Server not found' or similar errors after completing authentication at the Raven server it is likely that this aspect of the configuration is not correct. Setting Apache's 'ServerName' directive would be one way to resolve problems.
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. Unfortunatly 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 is a very bad idea since it will cause problems if 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
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.
Jon Warbrick, June 2010
