View source for 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. This page describes how to use this module in conjunction with the [http://www.ucs.cam.ac.uk/lookup/ldapqueries lookup LDAP service] and [http://raven.cam.ac.uk/project/apache/ mod_ucam_webauth]. These two Apache modules will allow you to restrict areas of your website to: 

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

For further information see the [http://www.ucs.cam.ac.uk/lookup/ldapqueries lookup LDAP service webpage] and/or the [http://httpd.apache.org/docs/2.4/mod/mod_authnz_ldap.html Apache mod_authnz_ldap webpage]

== Compatibility ==

All these examples have been tested with Apache 2.4. The same directives should work with Apache 2.2 but this hasn't been tested.

== Enabling modules ==

You need to enable the Apache modules <tt>authnz_ldap</tt> and <tt>ldap</tt>. You do this by adding suitable LoadModule directives to your Apache configuration, or by executing appropriate commands, such as (for Debian/Ubuntu/SLES systems):

  a2enmod authnz_ldap
  a2enmod ldap

You will also need to have installed [http://raven.cam.ac.uk/project/apache/ mod_ucam_webauth] to interact with raven.

The <tt>ldap</tt> module caches authentication and authorization results based on its configuration. Changes made to the backing LDAP server will not be immediately reflected on the HTTP Server. Consult the directives in [http://httpd.apache.org/docs/2.4/mod/mod_ldap.html mod_ldap] for details of the cache tunables.

== Security ==

Include the following Apache directive to make sure that all connections made by Apache to the LDAP server are secure.

  LDAPTrustedMode TLS
 
For Debian/Ubuntu systems you can add this to <tt>/etc/apache2/mods-enabled/ldap.conf</tt>

== Basic restrictions ==

You should use these directives in a protection block 

=== Allow access only to members of any institution (InstID) on a 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 directives can be used to check any other attribute of the user, not just instID, you will only need to replace the "instID=UIS" for whatever other attribute and value value you want to check that the user has.

DO NOT use displayName or many other Lookup attributes in an ldap-attribute check - displayName and many user attributes are user editable.

=== Allow access only to users (crsids) on a 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

=== Allow access only member of group on a 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 groupID=101855
  Require ldap-attribute groupID=101611

(where 101611=UIS staff and 101855=UIS test accounts). This works because groupIDs are an attribute of the user, just like any other attribute. Alternatively, the group short name may be used, for example:

  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 groupName=uis-members
  Require ldap-attribute groupName=uistest-members

=== More complex queries ===
 
More complex queries can be achieved using [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html#reqfilter 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"

(in practice note that 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 [http://httpd.apache.org/docs/2.2/mod/mod_authnz_ldap.html#reqfilter ldap-filter] or if you are using Apache 2.4.8 or greater, using [http://httpd.apache.org/docs/2.4/expr.html expressions].