Active Directory authentication

To enable Active Directory authentication, please set the $authenticateAgainst variable to “ACTIVE_DIR” in $HRM_CONFIG/hrm_client_config.inc and in $HRM_CONFIG/hrm_server_config.inc

<?php
...
// Authentication type: MYSQL, ACTIVE_DIR or LDAP
$authenticateAgainst = "ACTIVE_DIR";
...

Then, copy $HRM_SAMPLES/active_directory.config.inc.sample to $HRM_CONFIG/active_directory.config.inc and edit it.

<?php
// This file is part of the Huygens Remote Manager
// Copyright and license notice: see license.txt

// See http://adldap.sourceforge.net/wiki/doku.php?id=api_configuration for
// detailed help on configuring adLdap.

// The account suffix for your domain
$ACCOUNT_SUFFIX = "@mydomain.local";

// The base dn for your domain
$BASE_DN = "DC=mydomain,DC=local";

// Array of domain controllers. Specifiy multiple controllers if you would
// like the class to balance the LDAP queries amongst multiple servers
$DOMAIN_CONTROLLERS = array ("dc01.mydomain.local");

// Domain controller port
$AD_PORT = 389;

// User name suffix
$AD_USERNAME_SUFFIX = "";

// User name suffix matching string
$AD_USERNAME_SUFFIX_REPLACE_MATCH = "";

// User name suffix replacing string
$AD_USERNAME_SUFFIX_REPLACE_STRING = "";

// Optional account with higher privileges for searching (otherwise
// leave it to NULL). This should be set to a domain admin account (only
// read operations are performed!)
$AD_USERNAME = NULL;
$AD_PASSWORD = NULL;

// Tweak to get the real primary group from Active Directory. It works if
// the user's primary group is domain users.
// http://support.microsoft.com/?kbid=321360
$REAL_PRIMARY_GROUP = true;

// Use SSL (LDAPS)
$USE_SSL = false;

// Use TLS: if you wish to use TLS you should ensure that $USE_SSL is
// set to false and vice-versa
$USE_TLS = false;

// When querying group memberships, do it recursively
$RECURSIVE_GROUPS = true;

// Users usually belong to several groups. GROUP_INDEX defines
// which level of the hierarchy to consider (starts by 0). This
// obviously assumes that the sequence of groups memberships is
// constant among users. Set $GROUP_INDEX to -1 to get an array
// with all groups for the user. Please notice that this can also
// be used in combination with the next parameter.
$GROUP_INDEX = 0;

// If there is no way to get the desired group by using $GROUP_INDEX,
// this is an additional little trick. For this to work, $GROUP_INDEX
// MUST be set to -1, and the following array must contain the list of
// valid groups to be considered. This way, for each user the complete
// list of groups will be returned from the Active Directory, and of
// those, the one that is contained in the following array will be picked.
// If more than one matching group is found, the first will be taken. If
// no match is found, all groups will be returned.
// Fill the array as follows: $VALID_GROUPS = array( "group1", "group2" )
// with as many groups as you need.
$VALID_GROUPS = array( );

Special case: Active Directory forests

Warning

For most installations, you can skip the entire rest of this section and proceed with the next one by simply leaving the variables $AD_USERNAME_SUFFIX, $AD_USERNAME_SUFFIX_REPLACE_MATCH and $AD_USERNAME_SUFFIX_REPLACE_STRING with their default values (empty, i.e. "").

This part of the config is meant for the special case of an Active Directory with multiple domains (commonly referred to as forest) which usually consist of a top-level domain (the forest root domain) and several sub-domains. If the HRM users belong to domains in all levels of the forest it would be required to enter the full domain name for logging in, which can become quite tedious (and therefore error-prone).

Consider the following domain setup, a root domain called SATURN with two sub-domains RHEA and TETHYS. Those “plain” domain names are usually referred to as NetBIOS Domain Names. A hierarchical representation could look like this:

SATURN
  |
  +-- RHEA
  |
  +-- TETHYS

Now, assuming a top-level suffix of .private, in Microsoft’s Active Directory naming scheme this is translated into fully qualified domain names (FQDN’s) as follows. The root domain (SATURN) gets prefixed by ads. and followed by the top-level .private suffix, whereas the two subdomains just get postfixed by the FQDN of the root domain. The graphical representation from above would therefore translate into this:

ads.saturn.private
  |
  +-- rhea.ads.saturn.private
  |
  +-- tethys.ads.saturn.private

To make authentication work in such a scenario, it is required to authenticate against the GLOBAL CATALOG of the Active Directory. This is an LDAP service provided only on the domain controllers of the root domain on the special port 3268. The usernames used to authenticate have to be of the form username@fully.qualified.domain.name to provide the global catalog with the information to which sub-domain a certain account belongs as it is possible to have the same username for different accounts in different domains of a single domain forest.

Now given the HRM configuration option $ACCOUNT_SUFFIX would be set to .saturn.private, a user foo from the domain SATURN could log in using something like foo@ads whereas a user bar from RHEA would have to type bar@rhea.ads. This is obviously screaming for problems as normal users don’t understand where and why to put those weird suffixes, especially as they’ve never heard of something like ads before.

Using the sample config from below, users can simply log on by using their regular account name followed by an @ sign and the (short) NetBIOS domain name, e.g.

foo@saturn

or

bar@rhea

which is way easier to explain and remember for them, especially as the short domain names are usually visible for them when logging into their workstation.

<?php
...
$ACCOUNT_SUFFIX = "";
$BASE_DN = "DC=ads, DC=saturn, DC=private";

// set this to a domain controller of the *ROOT* domain:
$DOMAIN_CONTROLLERS = array("dc01.ads.saturn.private");

// the port is required to connect to the global catalog:
$AD_PORT = 3268;

// give the FQDN of the root domain with a leading dot here:
$AD_USERNAME_SUFFIX = ".ads.saturn.private";

// account names from the root domain will end up wrong, looking like this
// (note the leading "@" and the double occurence of the root domain):
$AD_USERNAME_SUFFIX_REPLACE_MATCH = "@saturn.ads.saturn.private";

// they have to be rewritten using the correct suffix instead (removing the
// first occurence of the root domain name):
$AD_USERNAME_SUFFIX_REPLACE_STRING = "@ads.saturn.private";
?>

Please feel free to contact the HRM developers in case you need help setting up authentication in a multi-domain forest scenario!