Mod authnz ldap

mod_authnz_ldap and lookup

The Apache module mod_authnz_ldap allows an LDAP directory to be used to store the database for HTTP Basic authentication. In this wiki page we are going to explain how to use this module in conjunction with the lookup LDAP service and mod_ucam_webauth. These two Apache modules will allow to restrict areas of your website to:

• A list of crsid
• Members of a any of the list of lookup groups
• Members of one the listed Institutions
• More complex combination of the previous statements

If you require more deep understanding or more information than the one provided in this page, you can visit the lookup LDAP service webpage and/or the Apache mod_authnz_ldap webpage

Compatibility

All these examples have been tested with Apache 2.4. The same directives could be used for Apache 2.2 but these haven't been tested.

Enabling modules

To enable the apache modules to make authnz_ldap to work, you will need to execute:

 a2enmod authnz_ldap
 a2enmod ldap

You will also need to have installed mod_ucam_webauth

Security

Include the following directive to the mod_ldap configuration to make sure that all connections make by Apache to the LDAP server are secure. Modify the file /etc/apache2/mods-enabled/ldap.conf and add

 LDAPTrustedMode TLS

This module caches authentication and authorization results based on the configuration of mod_ldap. Changes made to the backing LDAP server will not be immediately reflected on the HTTP Server. Consult the directives in mod_ldap for details of the cache tunables.

Basic restrictions

You should use these directives in a protection block

Only allow access to members of any institution (InstID) in the Require list

 AuthType Ucam-WebAuth
 AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk
 Require ldap-attribute instID=UIS
 Require ldap-attribute instID=CL

The same directive can be used to check any other attribute of the user, not only instID, you will only need to replace the "instID=UIS" for whatever other attribute value you want to check that the user need to have.

Allow access only to the users with crsids listed in Require list

 AuthType Ucam-WebAuth
 AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid
 Require ldap-user amc203
 Require ldap-user jw35
 Require ldap-user jml4

or

 AuthType Ucam-WebAuth
 AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid
 Require ldap-user amc203 jw35 jml4

DO NOT use displayName as a ldap-attribute check. displayName is a user editable field.

Allow access only member of any of the groups listed in the Require list and in the ldap query

 AuthType Ucam-WebAuth
 AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=groups,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk???|(groupID=101611)(groupID=101855)
 Require ldap-attribute groupID=101855
 Require ldap-attribute groupID=101611

(where 101611=UIS staff and 101855=UIS test accounts).

Groups should be identified by numeric ID since names could be duplicated (maliciously or accidentally), causing failure or bogus matches and consequent authorisation.

As you may have noticed, In case of groups, the ou parameter in AuthLDAPUrl needs to change from "people" to "groups and you need to include in the URL query the groups you want to authorise.

More complex queries

More complex queries can be achieved using ldap-filter which accepts expressions. You can use AND, OR, regex expressions, etc on different attributes.

Apache 2.4.8 or greater supports expressions in any ldap require directive.

Upgrading from old mod_ucam_lookupquery

The old module provided 5 different functions:

LookupInst

To restrict access to only members of certain Institutions.

Old code:

 Require LookupInst UIS CL 

New code:

  AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk
  Require ldap-attribute instID=UIS
  Require ldap-attribute instID=CL

LookupAttr

To restrict access to only members that match certain attribute values.

Old code:

 Require LookupAttr cn,displayName "Jon Warbrick" "Philip Hazel"

You should not use displayName because it is a user editable field.

New code:

  AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk
  Require ldap-attribute cn="Jon Warbrick"
  Require ldap-attribute cn="Philip Hazel"

LookupParentInst

This function is not supported

LookupUserInGroup

To restrict access to only members of certain lookup groups.

Old code:

 Require LookupUserInGroup 100001 100656

New code:

 AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=groups,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk???|(groupID=100001)(groupID=100656)
 Require ldap-attribute groupID=100001
 Require ldap-attribute groupID=100656

LookupQuery

More complex queries to the lookup service

Old code:

 RequireLookupQuery ou=groups sub (&(uid=%u)(groupTitle=*Computing Service*))

New code: More complex queries can be achieved using ldap-filter or if you are using Apache 2.4.8 or greater, using expressions.