Revision as of 13:50, 18 October 2012

Group-Office supports external authentication mechanims. An LDAP and IMAP authentication module are provided with the Group-Office download package.

It's easy to implement other authentication plugins. Read more about it here: http://www.group-office.com/wiki/Event_handling

Tip when testing these modules, it's wise to turn on $config['debug']=true; in config.php. It will print useful info to debug.log from version 3.5 and up.

How does it work

When a user logs in, the LDAP or IMAP server is queried first. If this authentication method fails then access is denied. If the user doesn't exist however, it will fall back to the normal Group-Office authentication. So if you want to block a user from loggin in using LDAP authentication, it's best to map a field to the "enabled" field of the Group-Office users. This way you can disable users from LDAP. Alternatively you can synchronize LDAP users.

LDAP authentication

Group-Office 3.01-stable-29 and up can use an LDAP server for authentication. It can also be used in conjunction with the imapauth module so it can automatically create an e-mail account for the user.

To setup LDAP authentication you need to install the "ldapauth" module and add the following configuration parameters to the config.php file:

$config['ldap_host']='localhost';
$config['ldap_port']='389';
$config['ldap_user']='admin';
$config['ldap_pass']='admin';
$config['ldap_basedn']='dc=intermeshdev,dc=nl';
$config['ldap_peopledn']='ou=People,dc=intermeshdev,dc=nl';
$config['ldap_groupsdn']='ou=Groups,dc=intermeshdev,dc=nl';
$config['ldap_tls']=false;
$config['ldap_auth_dont_update_profiles']=false; //set to true if you don't want ldap to overwrite the Group-Office user profile on each login
$config['ldap_use_uid_with_email_domain']='';//leave empty to use the default mapping. Set to a domain name to use username@example.com as e-mail address.

By default, Group-Office will search for uid=<USERNAME> in ldap. You can do something else if you define this config paramter:

$config['ldap_search_template']='uid={username}';

Group-Office will use the following mapping (Only uid, givenname, sn and mail are required at the LDAP server):

'username'	=> 'uid'
'first_name'	=> 'givenname'
'middle_name'	=> 'middlename'
'last_name'	=> 'sn'
'initials'	=> 'initials'
'title'	=> 'title'
'sex'		=> 'gender'
'birthday'	=> 'birthday'
'email'	=> 'mail'
'company'	=> 'o'
'department'	=> 'ou'
'function'	=> 'businessrole'
'home_phone'	=> 'homephone'
'work_phone'	=> 'telephonenumber'
'fax'		=> 'homefacsimiletelephonenumber'
'cellular'	=> 'mobile'
'country'	=> 'homecountryname'
'state'	=> 'homestate'
'city'	=> 'homelocalityname'
'zip'		=> 'homepostalcode'
'address'	=> 'homepostaladdress'
'homepage'	=> 'homeurl'
'work_address'=> 'postaladdress'
'work_zip'	=> 'postalcode'
'work_country'=> 'c'
'work_state'	=> 'st'
'work_city'	=> 'l'
'work_fax'	=> 'facsimiletelephonenumber'
'currency'	=> 'gocurrency'
'max_rows_list'	=> 'gomaxrowslist'
'timezone'	=> 'gotimezone'
'start_module'=> 'gostartmodule'
'theme'	=> 'gotheme'
'language'	=> 'golanguage'

You can customize this mapping by creating a file called ldapauth.config.php in the same directory as config.php is. Put the mapping in it like this:

<?php
$mapping=array(
						'username'	=> 'uid',
						'password'	=> 'userpassword',
						'first_name'	=> 'givenname',
						'middle_name'	=> 'middlename',
						'last_name'	=> 'sn',
						'initials'	=> 'initials',
						'title'	=> 'title',
						'sex'		=> 'gender',
						'birthday'	=> 'birthday',
						'email'	=> 'mail',
						'company'	=> 'o',
						'department'	=> 'ou',
						'function'	=> 'businessrole',
						'home_phone'	=> 'homephone',
						'work_phone'	=> 'telephonenumber',
						'fax'		=> 'homefacsimiletelephonenumber',
						'cellular'	=> 'mobile',
						'country'	=> 'homecountryname',
						'state'	=> 'homestate',
						'city'	=> 'homelocalityname',
						'zip'		=> 'homepostalcode',
						'address'	=> 'homepostaladdress',
						'homepage'	=> 'homeurl',
						'work_address'=> 'postaladdress',
						'work_zip'	=> 'postalcode',
						'work_country'=> 'c',
						'work_state'	=> 'st',
						'work_city'	=> 'l',
						'work_fax'	=> 'facsimiletelephonenumber',
						'currency'	=> 'gocurrency',
						'max_rows_list'	=> 'gomaxrowslist',
						'timezone'	=> 'gotimezone',
						'start_module'=> 'gostartmodule',
						'theme'	=> 'gotheme',
						'language'	=> 'golanguage',
			);

Mapping to contants

If you want to map a constant value you can do this:

'groupofficeAttribute'=>new GO_Ldapauth_Mapping_Constant('A contant value')

Mapping to a function

If you would like to do something advanced you can hook a custom function to an attribute:

'groupofficeAttribute'=>new GO_Ldapauth_Mapping_Function('custom_ldap_function'))


function custom_ldap_function(GO_Base_Ldap_Record $record){
return 'value';
}

Microsoft Active Directory

To use LDAP with Microsoft Active Directory you need to change the following mapping value in your ldapauth.config.php:

'username'      => 'samaccountname'

Now copy and paste these LDAP config lines into your config.php file for GO and change the values to your system needs.

$config['ldap_host']="someservernameyouhave";
$config['ldap_port']="389";
$config['ldap_user']="someLDAPusername";
$config['ldap_pass']="somepasswordtopermitLdapusertoSearchYourActiveDirectory";
$config['ldap_basedn']="dc=YouDomain, dc=COM_or_ORG_orwhatever";
$config['ldap_peopledn']="ou=SomeOrgUnitNameLikeSalesOrAccounting,dc=YourDomain,dc=com";
$config['ldap_groupsdn']="ou=SomeOtherOrgUnitContainingAccessGroups,dc=YourDomain,dc=com";
$config['ldap_tls']=false;
$config['ldap_auth_dont_update_profiles']=false;
$config['ldap_use_uid_with_email_domain']="";

Windows Server 2003 versus 2008 take note! If your domain is a Single Label Domain type and your LDAP server is 2003 use THIS format

$config['ldap_basedn']="dc=YouDomain";
$config['ldap_peopledn']="ou=SomeOrgUnitNameLikeSalesOrAccounting,dc=YourDomain";
$config['ldap_groupsdn']="ou=SomeOtherOrgUnitContainingAccessGroups,dc=YourDomain";

Note there is NO second "dc=" values set for a com or org value. You haven't got one if you are single label domain.

But if you use Windows 2008, you CANNOT do this. It won't let you and presents an error that says your Bind request for the LDAP server is an invalid format. So how do you do a single label domain if you can't define "nothing" for the second DC value? Step around it. Set this value:

$config['ldap_port']="3268";

Then use your single dc= references as described above. This port change calls upon the Global Catalogue server. You have to set your Domain controller up as a Global Catalogue.

Autocreating e-mail accounts

If this works you may configure the IMAP authentication module as described below. It's not necessary to install the imapauth module but it is necessary to create the imapauth.config.php file to autocreate e-mail accounts.

For the ldapauth module there is one extra parameter called "ldap_use_email_as_imap_username". Set it to true if you want to use the e-mail address to use as username for the imap server instead of the username.

IMAP authentication

Group-Office supports IMAP This means it will check an IMAP server for a valid account and will add/update the corresponding Group-Office account. To set this up you must install the "imapauth" module and rename "imapauth.config.php.example" to "imapauth.config.php" and put that file in the same directory as where your config.php file is.

When a user logs in it must login with the full e-mail address. Group-Office will use the domain part of the e-mail address and checks if the domain is in the "domains" setting in imapauth.config.php. When Group-Office finds a configuration it will attempt IMAP authentication. If it fails it will fall back on Group-Office authentication.

Then you must edit the values in the file. Below is a list of parameters.

Parameters

proto

The protocol. Can be IMAP or POP-3. IMAP is highly recommended. POP-3 is slow and doesn't offer the use of multiple e-mail folders.

domains

The domains this mail server configuration is valid for. It can be a comma separated list of domains (eg. "intermesh.nl,group-office.com"). You can also use * to match all domains.

host

The hostname of the machine where the mailserver runs.

port

The port. For IMAP usually 143 and for POP-3 usually 110.

ssl

SSL mode on or off

novalidate_cert

Validate the SSL certificate yes or no. with some mailservers you must enable this feature always even if you don't use SSL.

mbroot

The mailbox root. In most cases you can leave this value empty. It could be that you must enter “INBOX” or “mail” here.

smtp_host

The SMTP host to configure for new accounts

smtp_port

The SMTP port to configure for new accounts

smtp_encryption

Empty, tls or ssl

smtp_username

The username for SMTP authentication

smtp_password

The password for SMTP authentication

smtp_use_login_credentials

Set to true to use the login username and password for SMTP authentication too.

remove_domain_from_username

Enable this option if you want to remove the domain to the e-mail address. When you enable a user with e-mail john@example.com will login with "john@example.com" but GO will send "john" to the IMAP server.

create_email_account

If you want to create an e-mail account in Group-Office automatically when a user logs in the first time enable this option.

groups

Add the new users to these user groups automatically.

ldap_use_email_as_imap_username

Used in conjunction with "ldapauth" only. Set it to true if you want to use the e-mail address to use as username for the imap server instead of the username.

imapauth_combo_domains

String of domain names, separated by commas. These names will be put into the login dialog for quicker login.

imapauth_default_domain

Default domain for login dialog.

User rights for new imap users

To give new imap users the correct rights inside Group-Office you need to create a group for it. Then in the imapauth.config.php file you need to set the 'groups' parameter to the correct group.