Configuration/Authentication Settings/LDAP

From Davical
Jump to navigationJump to search

DAViCal supports LDAP Authentication. This page provides configuration settings and an example of configuring DAViCal with LDAP at version 0.9.3 and newer (the code itself sits in inc/drivers_ldap.php).

Some authentication examples, including LDAP, are also shown in Configuration, and in the config directory in the tarball.

For LDAP Authentication, it's important to install the LDAP modules for PHP (the php5-ldap package under debian/ubuntu).

Introduction

DAViCal has it's own user database. Even if you configure DAViCal to authenticate against your LDAP server, all it's going to do is trying to synchronize it's own database with the part of your LDAP tree you specified. The reason for that is simply, that DAViCal will always try to protect it's data and it won't take a missing LDAP user as enough of a reason to purge all his calendars and contacts. Instead it will render him 'inactive', so if you really wan't to get rid of a user you'll have to delete him twice: in your LDAP structure and via the DAViCal admin interface.

When a user logs in for the first time, an SQL record is created from the LDAP data using the mappings above: a cn entry in LDAP becomes username in SQL, all other attributes are mapped accordingly to your configuration file. If LDAP authentication is activated and configured DAViCal won't save the users password in the database! LDAP is to do the authentication after all. That also means that if you loose your LDAP data for some reason, your users won't be able to access their calendar or contacts either (but at least they'll still be there, which should be good news for you at this point.)

You import/sync users and groups via the "Administration --> Tools --> Sync with LDAP" menu in the web interface. It will check both, the users in your LDAP tree and the ones in it's own database. As said, if a user is absent in LDAP but active in DAViCal it will render him 'inactive' and thereby deny him access to any calendar ressources. Does the user exist on both sides, DAViCal will try to update the user according to the changes in its LDAP attributes, if any. If DAViCal finds users in your LDAP that it doesn't know about it will create a new user in it's SQL database. Therefor you should try to be precise when you define the user tree in the LDAP section of your DAViCal configuration - otherwise you'll end up with all sorts of useless accounts and ressources in your DAViCal database.

Support for group import was added in 0.9.9. You'll need the baseDNGroups, filterGroups and group_mapping_field set in the config to import groups (see the example below or the example-config.php in the source).

Supported features

Template:Tlist Template:TRlistOpenLDAP and ActiveDirectory support Template:TDlist Template:TRlistSSL, TLS and Unix socket support all in URI notation Template:TDliste.g. ldapi:// over Unix socket, ldaps://:636 over SSL and ldap://:389 over TLS Template:TRlistSupport for both anonymous and non-anonymous bind Template:TDlist Template:TRlistNo dependency at all on the schema that is being used Template:TDlistyou define the attribute mapping Template:TRlistGroup Mapping Template:TDlistsee LDAP_groups for slightly more information Template:TRlistSupport for filtered LDAP searches Template:TDlistallows to save bandwith and ressources by querying the LDAP server for a smaller subset of information Template:TRlistSupport for both the native application authentication and LDAP Template:TDlistthe current authentication hook allows for authentication to fall back to the local database Template:TRlistUser defined timeout durations for LDAP connections Template:TDlist Template:TRlistUser sync via CRON script Template:TDlist |}

LDAP Settings

The settings for the LDAP connection go in the config file /etc/davical/config.php (or perhaps /etc/davical/<servername>-conf.php).

  $c->authenticate_hook['call'] = 'LDAP_check';
  $c->authenticate_hook['config'] = array(
    'host'          => '<LDAP SERVER>',              //host name of your LDAP Server, use URI notation for LDAP over SSL on port 636
    'port'          => '<PORT>',                     //port
    'bindDN'        => '<BIND-CONTAINER/USERNAME>',  //DN to bind request to this server (if required)
    'passDN'        => '<PASSWORD>',                 //Password of request bind
    'baseDNUsers'   => 'cn=Users,dc=company,dc=com', //where to look for valid user
    'filterUsers' => 'objectClass=inetOrgPerson',    //filter which must validate a user according to RFC4515, i.e. surrounded by brackets
    'baseDNGroups' => 'ou=Groups,dc=company,dc=com', //where to look for groups
    'filterGroups' => 'objectClass=posixGroup',      //filter with same rules as filterUsers, could also be groupOfUniqueNames
    'protocolVersion' => 3,                          //important for simple auth (no sasl)
    'optReferrals'    => 0,                          //whether to automatically follow referrals returned by the LDAP server
    'networkTimeout'  => 10,                         //timeout in seconds
//    'startTLS'    => true,                         //securing your LDAP connection
    'mapping_field' => array(
                             'username' => 'uid',
                             'modified'  => 'modifyTimestamp',
                             'fullname' => 'cn',               //"Common Name"
//                           'user_no'  => 'uidNumber',        //set DAViCal user no to match Unix uid from LDAP (may cause sql_from_object problems if these user ids do not actually match...)
                             'email'    => 'mail',             
                             // 'active' => ,                  //switch calendar users on/off via ldap attribute
                             )
    'group_mapping_field' => array('username' => 'cn',
                             'modified' => 'modifyTimestamp',
                             'fullname' => 'cn' ,
                             'members' =>'memberUid'
                             ), //used to create the group based on the ldap properties
    'group_member_dnfix' => true, // if your "members" field contains the full DN and needs to be truncated to just the uid
    'default_value' => array("date_format_type" => "E","locale" => "en_EN"),
    'format_updated'=> array('Y' => array(0,4),
                             'm' => array(4,2),
                             'd' => array(6,2),
                             'H' => array(8,2),
                             'M' => array(10,2),
                             'S' => array(12,2)),              // map LDAP "modifyTimestamp" field to SQL "updated" field
     'scope' => 'subtree',                                     // Search scope to use, defaults to subtree (BOTH, user and group mappings)
  );
  include('drivers_ldap.php');

Explanation of parameters: Template:Tlist Template:TRlisthost Template:TDlistThe hostname of the LDAP server. Use DNS names or IP addresses or use URI notation for more specific ways to connect (e.g. ldap over SSL) Template:TRlistport Template:TDlistThe port to connect to the LDAP server on Template:TRlistbindDN Template:TDlistThe DN to bind to - leave this empty for anonymous authentication Template:TRlistpassDN Template:TDlistThe password for the bind - leave this empty for anonymous authentication Template:TRlistbaseDNUsers Template:TDlistThe base DN to look in for valid users Template:TRlistfilterUsers Template:TDlistA filter which must pass for this to be a valid user Template:TRlistbaseDNGroups Template:TDlistThe base DN to look in for valid group Template:TRlistfilterGroups Template:TDlistA filter which must pass for this to be a valid group Template:TRlistmapping_field Template:TDlistAn array of DAViCal field names vs. their LDAP mappings Template:TRlistgroup_mapping_field Template:TDlistAn array of DAViCal field names vs. their LDAP mappings Template:TRlistdefault_value Template:TDlistAn array of DAViCal field names vs. fixed default values Template:TRlistformat_updated Template:TDlistAn array, keyed on Y, m, d, H, M and S with the values being arrays of (start,length) for substring operations on the DAViCal 'updated' field sourced from LDAP. Template:TRlistscope Template:TDlistThe search scope for all LDAP searches (users and groups). Allowed values: base, onelevel, subtree. |}

Working Example

If your OpenLDAP server allows authentication from Apache 2.0 with an httpd config like:

 <IfModule mod_auth_ldap.c>
   AuthLDAPURL ldap://ldap.example.com/o=example
   AuthName "Example Inc. users"
   AuthType Basic
 </IfModule>
 order deny,allow
 deny from all
 require valid-user
 satisfy any

Then the following config allows authentication from DAViCal via LDAP:

$c->authenticate_hook['call'] = 'LDAP_check';
$c->authenticate_hook['config'] = array(
    'host' => 'www.tennaxia.net',
    'port' => '389',
    'bindDN'=> 'cn=manager,cn=internal,dc=tennaxia,dc=net',
    'passDN'=> 'xxxxxxxx',
    'baseDNUsers'=> 'dc=tennaxia,dc=net',
    'filterUsers' => 'objectClass=InetOrgPerson',
    'baseDNGroups' => 'ou=divisions,dc=tennaxia,dc=net',
    'filterGroups' => 'objectClass=posixGroup',
    'mapping_field' => array('username' => 'uid',
                             'modified'  => 'modifyTimestamp',
                             'fullname' => 'cn' ,
                             'email'    => 'mail'
                             ),
   'group_mapping_field' => array(
                            'username' => 'cn',
                            'modified' => 'modifyTimestamp',
                            'fullname' => 'cn' ,
                            'members'  =>'memberUid'
                            ),
    'group_member_dnfix' => true,
    'format_updated'=> array('Y' => array(0,4),
                             'm' => array(4,2),
                             'd' => array(6,2),
                             'H' => array(8,2),
                             'M' => array(10,2),
                             'S' => array(12,2))
    'scope' => 'subtree', 
    );
include_once('drivers_ldap.php');

Kerberos Authentication

You can use mod_auth_kerb in apache to get kerberos authentication for your davical accounts. Apache-Config Snippet:

  <Directory /usr/share/davical/htdocs/>
      AuthType Kerberos
      AuthName "Calendar Login"
      AllowOverride None
      Order allow,deny
      Allow from all

      Require valid-user
      # the following is available since mod_auth_kerb 5.4, it maps full kerberos principal "foo@FOOBAR.COM" to "foo"
      KrbLocalUserMapping On 
  </Directory>

The ldap configuration has to be extended with a:

  $c->authenticate_hook['config'] = array(
    // ...
    'i_use_mode_kerberos' => "i_know_what_i_am_doing",
    // ...
  );

Updating User Information from LDAP

This option will only appear in the tools section of the admin web interface if you have configured DAViCal to operate with your LDAP server.

It allows you to synchronise the DAViCal user database with the LDAP one. Normally this should be unecessary, since a synchronisation happens for a user when their information in DAViCal is older than that from LDAP, but it can be useful to use to prepopulate DAViCal so that you can configure groups and grants before people log in and use their calendars.

Prevent single users from being synced from LDAP

If there is some user you do not want to sync from LDAP, put their username in this list:

For example:

$c->do_not_sync_from_ldap = array( 'admin' => true, 'mrbond' => true );

This would set user's 'admin' & 'mrbond' to not be synchronised from your LDAP data. This can be useful if you want to retain a DAViCal specific Administrative user without having a user of that name in your LDAP database, or any other reason you can think up for wanting to have DAViCal users who are not in LDAP...

Fallback to internal authentication on failure

In some cases it is desirable that you fallback to DAViCal's internal authentication when external authentication fails. You might desire this if you have some locally configured users in addition to the majority who are in the LDAP server.

In such a case you can set:

$c->authenticate_hook['optional'] = true;

in your configuration file. This doesn't make authentication optional: everyone will still need a username and password! It just means that for someone who is not present in the external authentication system their credentials will then be checked against the internal system and they'll be allowed in if that matches then.

Template:AvailableFrom