Using the Lookup directory with Apache¶
In the Raven "golden rules" we noted that the University's Lookup directory should be used as an authoritative source of information on users.
Lookup has a LDAP personality which can be used to retrieve information on University members. Many applications will have native support for LDAP. We can't cover them all here. This page discusses using the LDAP personality of Lookup with Apache.
The mod_authnz_ldap module can be used to add LDAP support to an Apache web-server. This module is usually available via an Operating System package. For example, on Debian or Ubuntu machines the module is included with the basic Apache install and can be enabled via the following commands:
a2enmod authnz_ldap
a2enmod ldap
Important
The mod_ldap module used by mod_authnz_ldap includes a cache. This means that changes in Lookup will not immediately be reflected on your site. See the mod_ldap documentation for information on how to tune the caching.
You must ensure that all connections between Apache are secured using TLS (Transport Layer Security). On Debian or Ubuntu systems this can be achieved by adding the following to /etc/apache2/mods-enabled/ldap.conf
:
LDAPTrustedMode TLS
The examples on this page assume you are using Raven OAuth2. We also assume you've used the OIDCRemoteUserClaim
parameter to extract the local part of the user's email address within the <VirtualServer>
section:
OIDCRemoteUserClaim email "^(.*)@"
Danger
By using Lookup as the only user directory and splitting off the domain-part of the user's email address we are restricting ourselves to users who have CRSids. As noted in the Raven "golden rules" this will make it hard for you to add additional users to your site in future.
Authentication to Lookup LDAP¶
Unauthenticated access to the Lookup LDAP personality is only available within the CUDN. For Cloud-hosted applications the ldap connection will need to bind to the groupid
of the group you have setup a password for in Lookup.
These can be configured with the following directives:
AuthLDAPBindDN groupid=GROUPID,ou=groups,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk
AuthLDAPBindPassword GROUP_PASSWORD
Allowing only members of an institution or institutions¶
Within a VirtualServer
section include the following:
<Location />
AuthType openid-connect
<RequireAll>
Require valid-user
Require claim "hd:cam.ac.uk"
<RequireAny>
AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid
# List Lookup "instid"s for each allowed institution
Require ldap-attribute instID=UIS
Require ldap-attribute instID=CL
</RequireAny>
</RequireAll>
</Location>
Allowing only a whitelisted set of users¶
Within a VirtualServer
section include the following:
<Location />
AuthType openid-connect
<RequireAll>
Require valid-user
Require claim "hd:cam.ac.uk"
<RequireAny>
AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid
# List users separated with whitespace
Require ldap-user spqr1 fjc55
</RequireAny>
</RequireAll>
</Location>
Allowing only members of a Lookup group or groups¶
Within a VirtualServer
section include the following:
<Location />
AuthType openid-connect
<RequireAll>
Require valid-user
Require claim "hd:cam.ac.uk"
<RequireAny>
AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid
# List Lookup "groupid"s for each allowed group. Use "groupName"
# instead of "groupID" to use the group short name. Using the short
# name is not robust against groups being renamed.
Require ldap-attribute groupID=101855
Require ldap-attribute groupID=101611
</RequireAny>
</RequireAll>
</Location>
Allowing only users with Raven 2SV enabled¶
Simply use the groupID
(105223) of the Raven two-step verification lookup group, e.g.
Require ldap-attribute groupID=105223
More complex queries¶
The ldap-filter directive can be used to form more complex queries specifying who can access a site and is a good choice if you need to support non-@cam.ac.uk
users on your site.