Setting up the Creation Plug-in

Last Modified: 07-March-2014

This document covers the installation and setup of the user creation plug-in (plg_ldap_creation) that can be found in version 2. This plug-in is used to provision users to both Joomla and LDAP. It is assumed pkg_ldap_plugins has been installed by following the installation in Configuring LDAP Settings.

Jump to:
  1. Preparing the Template
  2. Configuring the Plug-in

Preparing the Template

This section demonstrates how to write and maintain the user creation XML and helper file templates. This is required to correctly write user attributes to the LDAP server. A basic understanding of XML syntax is required before proceeding.

It is recommended to inspect the example templates that include attributes from Active Directory and OpenLDAP schemas.

The optional helper file (i.e. the PHP file) that is associated with each template allows dynamic strings to be generated for attribute values.

The remainder of this section will demonstrate how to build the template.

The following is an example of the user creation XML:

<?xml version="1.0" encoding="UTF-8"?>
<templates>
	<template domain="openldap">
		<dn type="helper" />
		<username type="form">username</username>
		<password type="form">password_clear</password>
		<email type="form">email</email>
		<name type="form">name</name>
		<attribute name="objectClass" type="string">inetOrgPerson</attribute>
		<attribute name="objectClass" type="string">posixAccount</attribute>
		<attribute name="objectClass" type="string">shadowAccount</attribute>
		<attribute name="gidNumber" type="string">1000</attribute>
		<attribute name="givenName" type="helper" />
		<attribute name="homeDirectory" type="helper" />
		<attribute name="loginShell" type="string">/bin/bash</attribute>
		<attribute name="sn" type="helper" />
		<attribute name="uidNumber" type="helper" />
	</template>
</templates>

The following is an example of an accompanying PHP helper file:

final class LdapCreation_openldap
{
	const UID_NAME = 'ldap:uid';

	const UID_DEFAULT = 1001;

	public function getMandatoryDN($form)
	{
		$username = SHLdapHelper::escape($form['username'], true);

		return "uid={$username},ou=People,dc=shmanic,dc=net";
	}

	public function getGivenName($form)
	{
		if ($pos = strrpos($form['name'], ' '))
		{
			return substr($form['name'], 0, $pos);
		}

		return $form['name'];
	}

	public function getSn($form)
	{
		return substr($form['name'], strrpos($form['name'], ' ') + 1);
	}

	public function getHomeDirectory($form)
	{
		return "/home/{$form['username']}";
	}

	public function getUidNumber()
	{
		$db = JFactory::getDbo();

		$uid = $db->setQuery(
			$db->getQuery(true)
				->select($db->quoteName('value'))
				->from($db->quoteName('#__sh_config'))
				->where($db->quoteName('name') . ' = ' . $db->quote(self::UID_NAME))
		)->loadResult();

		if ($uid)
		{
			$db->setQuery(
				$db->getQuery(true)
					->update($db->quoteName('#__sh_config'))
					->set(array($db->quoteName('value') . ' = ' . $db->quoteName('value') . ' + 1' ))
					->where($db->quoteName('name') . ' = ' . $db->quote(self::UID_NAME))
			)->loadResult();
		}
		else
		{
			$db->setQuery(
				$db->getQuery(true)
					->insert($db->quoteName('#__sh_config'))
					->columns(array($db->quoteName('name'), $db->quoteName('value')))
					->values($db->quote(self::UID_NAME) . ', ' . $db->quote(self::UID_DEFAULT + 1))
			)->loadResult();

			$uid = UID_DEFAULT;
		}

		return $uid;
	}

	public function onAfterCreation($user, $attributes, $adapter)
	{
	}
}

Both of these files together form the creation template. It is recommended to name these files the same as the domain (e.g. openldap.php and openldap.xml). The location of these files is based on the parameter set for 'Template Base'.

The helper file must use the class LdapCreation_[domain] replacing [domain] with the LDAP configuration name used. In the example, the domain is openldap hence the class name is LdapCreation_openldap.

The following table explains the elements and attributes in the XML using the above template example:

Path / Element Attribute or Tag Description Used in Example

/templates/template/*

[Attribute] type

The type used to generate the value. This attribute has to be defined. There are 4 different types:

  • string - the value specified in the XML for the element is used. This should be used when defining always static attribute values. For example, the loginShell attribute will always use /bin/bash as the value.
  • form - the field name used in the registration form. This should be used when an attribute uses a field value as defined from the user registration form. For example, the email attribute uses the value specified in the email field.
  • helper - uses the return value from a method defined in the helper file. This should be used when a value needs to be dynamically generated (or manipulated). The method name called depends on whether it is a mandatory or standard attribute value. Mandatory fields (dn, username, password, email, name) call getMandatory[field]() like getMandatoryDN($form). The standard attributes call get[field]() like getGivenName($form). The form array is always passed as the first parameter.
    For example, the uidNumber calls the getUidNumber($form) which then gets a unique number from the database and then returns it.
  • eval - evaluates the PHP code as defined from the element value. Refer to the eval function documentation.

/templates/template

[Attribute] domain

This must be the name (also known as the domain) of the LDAP host configuration.

Value openldap meaning the LDAP host configuration for this user creation template is named openldap.

/templates/template/dn

[Tag] dn

The generated distinguished name for the new user. This has to be defined.

In the example, it is being pulled from the helper method getMandatoryDN() which would return:

uid=[username],ou=People,dc=shmanic,dc=net

/templates/template/username

[Tag] username

The generated username for the new user.

In the example, the value of the username form field is used.

Note: the inbuilt Joomla registration form uses username to represent the username.

/templates/template/password

[Tag] password

The generated password for the new user.

In the example, the value of the password_clear form field is used.

Note: the inbuilt Joomla registration form uses password_clear to represent the password.

/templates/template/email

[Tag] email

The generated email for the new user.

In the example, the value of the email form field is used.

Note: the inbuilt Joomla registration form uses email to represent the email.

/templates/template/name

[Tag] name

The generated full name for the new user.

In the example, the value of the name form field is used.

Note: the inbuilt Joomla registration form uses name to represent the full name.

/templates/template/attribute

[Attribute] name

The name of the LDAP attribute to use. This has to be defined for the 'attribute' elements.

Lets look at three examples:

gidNumber means the attribute gidNumber is passed to the LDAP server with the value 1000 for the new user.

givenName means the attribute givenName is passed to the LDAP server with the value taken from the getGivenName() helper method for the new user.

objectClass is defined 3 times in the example. This means the attribute objectClass will have 3 values of inetOrgPerson, posixAccount and shadowAccount before being passed to the LDAP server for the new user.

Make sure the template looks like the example templates. Ensure it is saved inside the directory specified by the 'Template Base' parameter.

Back to Top

Configuring the Plug-in

This section demonstrates the usage for the profile plug-in parameters.

  1. Open the 'LDAP - User Creation' configuration through the Plug-in Manager.
  2. The following table shows the usage and examples of each parameter in the plug-in:
    Key Description / Examples / Usage
    Template Name

    Specify the template name. This is the same name as the XML excluding the file extension.

    Example: If the template XML is named 'openldap.xml' then enter openldap as the value.

    Template Base

    Specify the full path to the template base directory. This is where the template XML and helper are stored.

    Examples:

    • /etc/joomla/ldap_creation
    • c:/mysites/ldap_creation
    Delete on Fail

    If user creation fails, attempt to delete the user from LDAP if one was created.

  3. Set the plug-in to the Enabled state and click Save.