Revision as of 08:08, 8 July 2015

Group-Office supports external authentication mechanisms. 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.

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.

//Available since 4.2.17. Instruct the "serverclient" module to create mailboxes for these domains. The serverclient module must be configured. See [[Mailserver#Optionally_install_the_serverclient]].
//leave the imapauth.config.php empty in this case. 
$config['ldap_create_mailbox_domains']=array("intermesh.dev");

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'	=> new \GO\Ldapauth\Mapping\Constant('en'),
	'enabled'	=> new \GO\Ldapauth\Mapping\FunctionMapping('custom_ldap_mapping_function_enabled'),
	'exclude'	=> new \GO\Ldapauth\Mapping\FunctionMapping('custom_ldap_mapping_function_exclude'),
);

if (!function_exists('custom_ldap_mapping_function_enabled')) {
	function custom_ldap_mapping_function_enabled(\GO\Base\Ldap\Record $record){
		return $record->{"SOME-LdapAttribute"}[0]=="TRUE" ? 1 : 0;
	}
}

if (!function_exists('custom_ldap_mapping_function_exclude')) {
	function custom_ldap_mapping_function_exclude(\GO\Base\Ldap\Record $record){
		return $record->{"SOME-LdapAttribute"}[0]=="TRUE" ? 1 : 0;
	}
}

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"; //FROM 5.1.3 you can use {VDOMAIN} in the peopledn. it will be replaced with the domain of the email address that has to be used for login.
$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

You can 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.

If you use the "postfixadmin" module to manage the e-mail accounts you can also use $config['ldap_create_mailbox_domains'] (see above) to create email accounts.

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 authenticate using the IMAP server.

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.

store_password By default the passwords are stored using two way encryption in the database. The encryption key is stored on disk and not in the database. You can disable this and not store the password at all but just keep it in the session. The downside is that email accounts can't be shared when you don't store passwords.

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.

Example config file

<?php
/**
 * For more information visit: http://wiki4.group-office.com/wiki/IMAP_or_LDAP_authentication
 */

$config[] =
	array(
	'proto' => 'imap',
	'domains' => '*',
	'host' => 'localhost',
	'port' => '143',
	'ssl' => false,
	'novalidate_cert' => false,
	'mbroot' => '',//you might have to change this to INBOX
	'remove_domain_from_username' => false,
	'create_email_account' => true,
	'groups' => array('Internal'),

	'store_password'=>true, //By default the passwords are stored using two way encryption in the database. The encryption key is stored on disk and not in the database. You can disable this and not store the password at all but just keep it in the session. The downside is that email accounts can't be shared when you don't store passwords.


	'smtp_host'=>'localhost',
	'smtp_port'=>'25',
	'smtp_encryption'=>'',
	'smtp_username'=>'',
	'smtp_password'=>'',
	'smtp_use_login_credentials'=>false, //set to true to use the login username and password for SMTP authentication too.

	'ldap_use_email_as_imap_username'=>false,
	'imapauth_combo_domains' => 'example.com,example2.com',
	'imapauth_default_domain' => 'example.com'
	);


//$config[] =
//	array(
//	'proto' => 'imap',
//	'domains' => 'example.com', //for different imap servers you can define them with the explicit domain name
//	'host' => 'localhost',
//	'port' => '143',
//	'ssl' => false,
//	'novalidate_cert' => false,
//	'mbroot' => '',//you might have to change this to INBOX
//	'remove_domain_from_username' => false,
//	'create_email_account' => true,
//	'groups' => array('Internal'),
//
//	'smtp_host'=>'localhost',
//	'smtp_port'=>'25',
//	'smtp_encryption'=>'',
//	'smtp_username'=>'',
//	'smtp_password'=>'',
//	'smtp_use_login_credentials'=>false, //set to true to use the login username and password for SMTP authentication too.
//
//	'ldap_use_email_as_imap_username'=>false,
//	'imapauth_combo_domains' => 'example.com,example2.com',
//	'imapauth_default_domain' => 'example.com'
//	);
?>