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

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 "^(.*)@"

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.