Mod authnz ldap: Difference between revisions

From RavenWiki
Jump to navigationJump to search
(Replace with link to Raven wiki)
 
(4 intermediate revisions by 3 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]. These two Apache modules will allow to restrict areas of your website to:  
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:  


* A list of crsid
* A list of crsid
* Members of a any of the list of lookup groups
* Members of a any of the list of lookup groups
* Members of one the listed Institutions
* Members of any of a list of Institutions
* More complex combination of the previous statements
* 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 [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]
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 ==
== Enabling modules ==


To enable the apache modules to make authnz_ldap to work, you will need to execute:
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 authnz_ldap
   a2enmod ldap
   a2enmod ldap


You will also need to have installed [http://raven.cam.ac.uk/project/apache/ mod_ucam_webauth]
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
 
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 [http://httpd.apache.org/docs/2.4/mod/mod_ldap.html mod_ldap] for details of the cache tunables.
For Debian/Ubuntu systems you can add this to <tt>/etc/apache2/mods-enabled/ldap.conf</tt>


== Basic restrictions ==
== Basic restrictions ==
Line 35: Line 37:
You should use these directives in a protection block  
You should use these directives in a protection block  


=== Only allow access to members of any institution (InstID) in the Require list ===
=== Allow access only to members of any institution (InstID) on a list ===


   AuthType Ucam-WebAuth
   AuthType Ucam-WebAuth
Line 42: Line 44:
   Require ldap-attribute instID=CL
   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.
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.


=== Allow access only to the users with crsids listed in Require list ===
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
Line 58: Line 62:
   Require ldap-user amc203 jw35 jml4
   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 group on a list ===
 
=== Allow access only member of any of the groups listed in the Require list and in the ldap query ===


   AuthType Ucam-WebAuth
   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)
   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=101855
   Require ldap-attribute groupID=101611
   Require ldap-attribute groupID=101611


(where 101611=UIS staff and 101855=UIS test accounts).
(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:


Groups should be identified by numeric ID since names could be duplicated (maliciously or accidentally), causing failure or bogus matches and consequent authorisation.
  AuthType Ucam-WebAuth
 
  AuthLDAPUrl ldap://ldap.lookup.cam.ac.uk/ou=people,o=University%20of%20Cambridge,dc=cam,dc=ac,dc=uk
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.
  Require ldap-attribute groupName=uis-members
  Require ldap-attribute groupName=uistest-members


=== More complex queries ===
=== More complex queries ===
Line 102: Line 105:
   Require LookupAttr cn,displayName "Jon Warbrick" "Philip Hazel"
   Require LookupAttr cn,displayName "Jon Warbrick" "Philip Hazel"


You should not use displayName because it is a user editable field.
(in practice note that you should not use displayName because it is a user editable field).


New code:
New code:

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.