Mod authnz ldap: Difference between revisions

From RavenWiki
Jump to navigationJump to search
(Replace with link to Raven wiki)
 
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
= mod_authnz_ldap and lookup =
= 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 [http://www.ucs.cam.ac.uk/lookup/ldapqueries lookup LDAP service] and [http://raven.cam.ac.uk/project/apache/ mod_ucam_webauth].
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 [[Apache_authentication_module | mod_ucam_webauth]]. These two Apache modules will allow you to restrict areas of your website to:


If you require more deep information than the one provided in this page, you can visit 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]
* 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 ==
== 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.
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 [[Apache_authentication_module | 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 ==
== 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
Include the following Apache directive to make sure that all connections made by Apache to the LDAP server are secure.


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


== Basic documentation ==
== Basic restrictions ==


You should use these directives in a protection block


=== Only allow access to members of an institution (InstID) ===
=== 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
   AuthType Ucam-WebAuth
   AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid
   AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid
   Require valid-user
   Require ldap-user amc203
   Require ldap-filter instID=UIS
  Require ldap-user jw35
   Require ldap-user jml4


=== Only allow access to members of any institution (InstID) in the RequireAny list ===
or


   AuthType Ucam-WebAuth
   AuthType Ucam-WebAuth
   AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid
   AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid
   <RequireAll>
   Require ldap-user amc203 jw35 jml4
    Require valid-user
 
    <RequireAny>
=== Allow access only member of group on a list ===
      Require ldap-filter instID=UIS
      Require ldap-filter instID=CL
    </RequireAny>
  </RequireAll>


  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


=== Allow access only to the users with crsids listed in RequireAny ===
(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
   AuthType Ucam-WebAuth
   AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid
   AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk
   <RequireAll>
   Require ldap-attribute groupName=uis-members
    Require valid-user
  Require ldap-attribute groupName=uistest-members
    <RequireAny>
 
      Require ldap-user amc203
=== More complex queries ===
      Require ldap-user jw35
      Require ldap-user jml4
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.
    </RequireAny>
 
   </RequireAll>
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


=== Allow access only member of any of the groups listed in the RequireAny tag and in the ldap query ===
=== LookupQuery ===


  AuthType Ucam-WebAuth
More complex queries to the lookup service
  AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=groups,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk?uid??|(groupID=101611)(groupID=101855)
  <RequireAll>
    Require valid-user
    <RequireAny>
      Require ldap-attribute groupID=101855
      Require ldap-attribute groupID=101611
    </RequireAny>
  </RequireAll>


(where 101611=UIS staff and 101855=UIS test accounts).
Old code:
  RequireLookupQuery ou=groups sub (&(uid=%u)(groupTitle=*Computing Service*))


Groups should be identified by numeric ID since names could be duplicated (maliciously or accidentally), causing failure or bogus matches and consequent authorisation.
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].

Latest revision as of 13:50, 13 December 2019

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 lookup LDAP service and 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 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 should work with Apache 2.2 but this hasn't been tested.

Enabling modules

You need to enable the Apache modules authnz_ldap and ldap. 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 mod_ucam_webauth to interact with raven.

The ldap 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 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 /etc/apache2/mods-enabled/ldap.conf

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 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 ldap-filter or if you are using Apache 2.4.8 or greater, using expressions.

Retrieved from "https://wiki.cam.ac.uk/wiki/raven/index.php?title=Mod_authnz_ldap&oldid=2892"