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: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:
|
|
/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.
Configuring the Plug-in
This section demonstrates the usage for the profile plug-in parameters.
- Open the 'LDAP - User Creation' configuration through the Plug-in Manager.
- 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.
-
Set the plug-in to the Enabled state and click Save.