Do It The jAPS Way
Copyright © 2009 AgileTec s.r.l.
Legal Notice
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the Appendix entitled "GNU Free Documentation License".
2011-02-18
| Revision History | ||
|---|---|---|
| Revision 1.0 | 2011-02-18 | MEM |
|
First English translation | ||
Abstract
The aim of this document is to provide a full description of the structure of the Ldap plugin.
Table of Contents
List of Tables
List of Examples
Table of Contents
The purpose of this document is to provide a complete description
of the Plugin LDAP (jpldap) structure.
This document is intended for those who wish to know the
capabilities of the LDAP plugin (jpldap) and
are considering the possible integration into a running production
environment or in its Development Environment (IDE Eclipse Project).
The document is addressed to both System Administrators and java Developers with a basic understanding of the JAPS 2.0 entando platform.
In order to take maximum advantage from the present document, it is necessary to have basic knowledge about: Java platform, Eclipse development tools, the servlet engine Apache Tomcat, PostgreSQL dbms, jAPS 2.0 Framework.
Moreover, it's necessary to have read jAPS 2.0 Plugin Pattern document.
Additional informations may be obtained through the official mailing-lists:
<japs-platform@googlegroups.com>, "japs-platform" Google Group, the jAPS 2.0 entando official Mailing List
Is it also possible to refer to the documentation found in the:
Table of Contents
The jpldap plugin enables the system connection to a LDAP server (including Microsoft ones) to
enlarge the base of system users. These imported users are handled in the same way of the local ones.
Furthermore the plugin may leave the authentication process to the LDAP server without affecting or changing the way the authorisation are handled: both local and remote users are managed with the standard jAPS 2.0 entando user management interface.
Table 2.1. Characteristics Summary
| Code | Name | Type | Plugin Version | Version of jAPS 2.0 entando |
|---|---|---|---|---|
| jpldap | LDAP | Modification | 1.1 | 2.2.0 - |
| jpldap | LDAP | Modification | 1.0 | 2.0.2 - 2.0.10 |
This plugin does not add new user interfaces in both the front end and in the back office.
The new external users acquired from a LDAP source are managed in the same way of the "local"
users (that is, users held in the serv database of your
jAPS 2.0 entando installation).
Some restrictions to the management of the LDAP users apply: you can neither delete nor modify a LDAP user. This behaviour is intended.
Table of Contents
This plugin is classified as Modification because it modifies the user management engine to allow remote authentication (in this case, on a LDAP server). The definition and the associations of the authorisations are not modified, but they can be applied - through the usual jAPS back office interfaces - to both local and remote users.
The plugin modifies the core user manager engine, namely the
UserManager.
The UserManager bean injected by the Spring framework is
overwritten so to introduce the support for remote authentication
(performed by the Authentication Provider service)
and to make possible the user search in the LDAP directory.
The plugin works in Read Only mode.
The LDAP plugin does not allow the modification or the deletion of the objects (users) in the Directory; the structure cannot be changed as well. The Plugin (and so jAPS by extension) is not responsible for the LDAP users -intended as objects in the LDAP directory!- administration which is responsibility of the Domain administrator.
The package contains all the plugin directory (directory
doc, src
and the Readme file) defined by
jAPS2.0 Plugin Pattern
document.
In particular, the directory
src
is structured as described below:
The
javadirectory. It contains java sources and the jUnit tests for the plugin.Since the plugin doe not add any user interface, the directory only contains the file for the bean definition of the new manager.
From now we will use the name myportal
when referring to your deployed jAPS 2.0 entando Application.
In order to execute the integration in a web application based on jAPS 2.0 entando compatible with the plugin, follow this procedure:
- Stop the servlet container
Copy the content of
src/webapp/WEB-INF/libdirectory, from the provided package, tomyportal/WEB-INF/lib/directory.Create the directory
myportal/WEB-INF/plugins/if it does not exist. Copy the content ofsrc/webapp/WEB-INF/plugins/directory, from the provided package, tomyportal/WEB-INF/plugins/just created.Insert the following parameters properly configured (
ldap.provider.url,ldap.provider.securityPrincipal,ldap.provider.securityCredentials,ldap.provider.userObjectClass,ldap.provider.userIdAttributeName,ldap.provider.filterGroup,ldap.provider.filterGroupAttributeName) in the filemyportal/META-INF/context.xmlof your jAPS 2.0 entando installation.
As a convention, we call the project where the plugin is about to be installed myproject.
To perform the installation of jpldap in an Eclipse IDE, on a version of jAPS 2.0 entando compatible with the plugin, follow these steps:
- Stop the servlet container
Copy the content of the directory
src/webapp/WEB-INF/pluginsof the provided package, inside themyproject/WebContent/WEB-INF/plugins/.Insert the following parameters (described more in depth in the next chapter)
ldap.provider.url,ldap.provider.securityPrincipal,ldap.provider.securityCredentials,ldap.provider.userObjectClass,ldap.provider.userIdAttributeName,ldap.provider.filterGroupandldap.provider.filterGroupAttributeName, properly configured, in the filemyportal/META-INF/context.xml,myproject/WebContent/WEB-INF/conf/ANTsystemParams.propertiesandmyproject/admin/test/systemParams.properties.Copy the content of the directory
src/java/main/comin themyproject/src/comdirectory
Once the following steps are performed, restart your project and verify the connection toward the wanted LDAP server by looking for users coming from external sources in the user administration interface.
A number of parameter must be properly configure to ensure the correct connection to the desired LDAP server (OpenLDAP and Microsoft Active Directory are supported)
These parameters must be inserted as environment variables in the following configuration file:
/META-INF/context.xml
Example 4.1. An example of the LDAP plugin configuration
<!-- jpldap -->
<Environment name="ldap.provider.url"
value="ldap://192.168.4.11:389/dc=mydomain,dc=com"
type="java.lang.String" override="false" />
<Environment name="ldap.provider.securityPrincipal"
value="" type="java.lang.String" override="false" />
<Environment name="ldap.provider.securityCredentials"
value="" type="java.lang.String" override="false" />
<Environment name="ldap.provider.userObjectClass"
value="posixAccount" type="java.lang.String" override="false" />
<Environment name="ldap.provider.userIdAttributeName"
value="uid" type="java.lang.String" override="false" />
<Environment name="ldap.provider.filterGroup"
value="" type="java.lang.String" override="false" />
<Environment name="ldap.provider.filterGroupAttributeName"
value="" type="java.lang.String" override="false" />
Please note that the declaration of the same parameters assumes a different form
for myproject/admin/test/systemParams.properties and
myproject/WebContent/WEB-INF/conf/ANTsystemParams.properties
Example 4.2. LDAP plugin configuration for *.properties files
ldap.provider.url=ldap://192.168.4.11:389/dc=mydomain,dc=com ldap.provider.securityPrincipal= ldap.provider.securityCredentials= ldap.provider.userObjectClass=posixAccount ldap.provider.userIdAttributeName=uid ldap.provider.filterGroup ldap.provider.filterGroupAttributeName=
The following parameters can be configured (only a few of them are mandatory):
ldap.provider.urlThe url of the LDAP server to connect to. This setting is mandatory.
ldap.provider.securityPrincipalUsername to use to connect the LDAP server. Leave it blank to make an anonymous connection; please note that Microsoft Active Directory does not allow anonymous connections. This parameters corresponds to the Distinguished Name: it is formed by the entry name itself (named Relative Distinguished Name, usually usually derived from some attribute of the entry) followed by the name of the parent entries separated by a comma.
ldap.provider.securityCredentialsThe password associated to the username for the connection to the server. It may be left blank for an anonymous connection (not allowed by a Microsoft Active Directory).
ldap.provider.userObjectClassName of the
objectClassentry used to map users. The specification of this parameter is mandatory, and it usually assumes two values:userfor the Active Directory domains andposixAccountfor the OpenLDAP domains. Different LDAP server implementations may require different values.ldap.provider.userIdAttributeNameName of the attribute entry that specifies the unique id of the LDAP user. The specification of this parameter is mandatory. This parameter usually assumes two values:
sAMAccountNamefor the Active Directory domains anduidfor the OpenLDAP domains. Different LDAP server implementations may require different values.ldap.provider.filterGroupDefinition of the name of the LDAP group to which users belong to. If you don't want to filter the users just leave this field blank.
ldap.provider.filterGroupAttributeNameName of the entry attribute that indicates the belonging to a LDAP group. If you don't want to filter the users just leave this field blank.
If the LDAP is not properly configured the answer from the server may be so huge to result in an excessive slowdown of the system eventually leading to a general failure.
To prevent this situation, the XML containing the bean definition of the
LDAP service, WEB-INF/plugins/jpldap/conf/managers/baseManagersConfig.xml,
contains a commented out property definition:
<!-- <property name="searchResultMaxSize">
<value>100</value>
</property> -->
This parameter can be toggled and used to limit the results returned by the LDAP manager so to estimate the performance degradation during the fine-tuning of the system.
