Step one:

Prepare your MS SQL server

Download and install MS SQL Server. For this article MS SQL 2008 R2 EXPRESS has been used. As of today, there is only MS SQL Server 2008 R2 officialy supported. However, it SHOULD work with all MS SQL Servers since MS SQL Server 2008.

During the installation you will be prompted if you want to use Windows authentication only or you want to allow also SQL authentication. In order to use MS SQL as OpenIDM’s repository, you have to allow SQL authentication as well.

Once the installation is finished, run the SQL Server Configuration Manager. Open SQL Server Network Configuration, click on Protocols for SQLEXPRESS, enable TCP/IP. When the TCP/IP is enabled double-click on TCP/IP, tab IP Addresses. There you can setup to which IP addresses and ports will the server listen. For this article, we will use the very last one – IPAll. Set the TCP Dynamic port to 1433 (The 1433 is default port for MS SQL.). And also don’t forget to adjust your firewall settings.

To apply new configuration the SQL Server has to be restarted. This can be done in SQL Server Services.

As a next step, run Microsoft SQL Server Management Studio (SSMS) (Comes with MS SQL Server. If not, download it from Microsoft’s web pages.) and login as a current user (e.g. Administrator).

Then open OpenIDM’s database definition SQL script from openidm/db/scripts/mssql/openidm.sql (File -> Open -> file or use shortcut ctrl + O) and execute it. The script will create a new database openidm and two new users – openidm and openidm_proxy.
The default password for both users is ‘Passw0rd’.

And that is it. The MS SQL Server is ready.

Step two:

Configure OpenIDM to use MS SQL Server as repository

There are few steps that need to be followed configure it – in short: you need to add jdbc driver to bundles and switch the repo.json files. So, let’s describe it in more detail.

Following steps to create jdbc driver jar file can also be found in openidm/db/scripts/mssql/sqljdbc4.bnd:

• Download sqljdbc_4.0.2206.100_enu.tar.gz from http://www.microsoft.com/en-us/download/details.aspx?id=11774 and extract sqljdbc4.jar from it.
• Then download biz.aQute.bnd.jar from http://dl.dropbox.com/u/2590603/bnd/biz.aQute.bnd.jar.
• Put both files to openidm/db/scripts/mssql/ folder and run following command from command line

  java -jar biz.aQute.bnd.jar wrap -properties sqljdbc4.bnd sqljdbc4.jar

• as result a sqljdbc4.bar should be generated. Rename it to sqljdbc4-osgi.jar and copy it to openidm/bundle.

One last thing is remaining and the setup is complete.

As of a day of writing this blog, there are only three kinds of resources supported as OpenIDM’s repository; namely OrientDB, MySQL and MS SQL. The repository configuration file for OrientDB is called repo.orientdb.json and for MS SQL and MySQL  is a common name – repo.jdbc.json. So, go to openidm/samples/misc and locate repo.jdbc-mssql.json which is pre-configured configuration file for MS SQL and copy it to openidm/conf directory.

Once the file is copied, rename it to repo.jdbc.json. However, the OpenIDM requires only one repository configuration file to be present in conf directory, so the other one has to be either deleted (in case of repo.orientdb.json) or overwritten (in case of repo.jdbc.json). If you are using another user to access the repository than the user created by SQL defenition script (user openidm), you need to change the credentials in repo.jdbc.json.

Now the configuration is complete and you can start OpenIDM and check if the MS SQL repo is working.

Our strartegic objective is to provide customers with the freedom and flexibility they need in deploying and using IAM products in enterprise, mobile, cloud and social environments, while avoiding vendor lock-in to cumbersome, proprietary vendor solutions. The ForgeRock Open Identity Stack is the key to enabling just that.

Our first priority is to help customers of former Sun AIM products. The support of Sun OpenSSO (Oracle OpenSSO), Sun Identity Manger (Oracle Waveset) and Sun OpenDS is going to end soon. ForgeRock’s Open Identity Stack is a world-wide supported continuation of Sun’s former AIM stack and provides an easy way forward without major disruptions to business. Should you operate any of

• Sun Directory Server, Sun OpenDS
• Sun Access Manager, Sun OpenSSO
• Sun Identity Manager

currently and searching for a way forward, contacts us! We have a smooth upgrade approach for you, both technology and business wise.

See the press release at http://integration.profiq.cz/about/press.php and a more detailed explanation of our services at http://integration.profiq.cz/services/

About OpenIDM & OpenICF

OpenIDM communicates with various kinds of resources from simple files (XML, CSV) to more complex ones, like various LDAP implementations and SQL databases. This communication is provided via Open Identity Connector Framework and Toolkit (OpenICF). If, for some reason, access libraries cannot be build-in to OpenIDM (cannot be included inside Java Virtual Machine) an external connector server is needed. This article covers deployment of OpenIDM on one machine and external .NET Connector Server where remote connector is implemented on second remote machine. In this deployment .Net Connector Server provides a way to connect OpenIDM with Microsoft Active Directory as depicted in below diagram:

Prerequisites

• Windows 2003 or 2008
• .NET Framework 4.0
• Microsoft Active Directory – In this setup I used the AD bundled with Windows 2008 RC2 SP1
• OpenIDM 2.1.0. revision 1395

Installing .NET Connector Server on Windows

1. Download connector server from here (tested on build #23 )
2. Execute the downloaded .msi file. Just follow the wizard. It will walk you through the whole process step by step. Upon completion, the Connector Server will be installed as a windows service called “Connector Server”.

Starting and Stopping the Connector Server

1. You can start or stop the server using Microsoft Services Console. Start -> type Services -> Services
2. Also you can start the server from command prompt. Start -> type cmd -> cmd. Change the directory to where the Connector Server has been installed, by default\Program Files\Identity Connectors\Connector Server

   C:\> cd “Program Files (x86)\Identity Connectors\Connector Server”

   and run the following command:

   ./ConnetorServer.exe /run

Configuring the .NET Connector Server

1. Start the Microsoft Services Console (Start -> type Services -> Services ). Check to see if the Connector Server is currently running. If so, stop it. From a command prompt (Start -> type cmd), set the key for the connector Server. This is done by changing to the directory where the connector server was installed and executing the following command:

   ./ConnectorServer.exe /setkey <newkey>

   where

   <newkey>

   is the string value. This key is required by any client that connects to this Connector Server.

2. See the ConnectorServer.exe.config for addtional configuration. The port, address, and SSL settings are in the tag called AppSettings, and look like this:

   <add key="connectorserver.port" value="8759" />
   <add key="connectorserver.usessl" value="false" />
   <add key="connectorserver.certificatestorename"
                 value="ConnectorServerSSLCertificate" />
   <add key="connectorserver.ifaddress" value="0.0.0.0" />

   • connectorserver.port – Sets the port
   • connectorserver.ifaddress – Accepting connections from particular address or all (0.0.0.0)
   • connectorserver.usessl – Turns on/off the SSL
   • connectorserver.certifacatestorename – If using certificates, put there your certificate store name

   Any configuration changes will require the connector server to be stopped and restarted.

3. Now, you need to add the active directory connector. Do it so by downloading active directory connector (tested on build #15) and simply unzipping it to Connector Server folder.
4. Start the Connector Server service (from Microsoft Service Console).
5. Make sure you have your firewall either turned off or add rule to your firewall to open port which you have set in ConnectorServer.exe.config

Configuring OpenIDM

1. When you configure remote connectors, you must use the connector info provider service to connect through remote connector servers. The configuration is stored in the configuration file, openidm/conf/provisioner.openicf.connectorinfoprovider.json. A sample can be found in openidm/samples/provisioners/.
2. Make sure the openidm is running and copy the provisioner.openicf.connectorinfoprovider.json to /path/to/openidm/conf and edit it according to your needs. In my case the file is provisioner.openicf.connectioninfoprovider.json

   $ cd path/to/openidm
   $ cp samples/provisioners/provisioner.openicf.connectorinfoprovider.json conf/

3. As next step you need to create connector file provisioner.openicf-ad.json in conf/ directory. The file should look like the following one provisioner.openicf-ad.json
4. Edit the configurationProperties according to your Active Directory setup and also make sure that the bundleVersion is the SAME version as ActioveDirectory.Connector.dll in Windows Connector Server folder. (Right click on the dll -> properties -> tab details -> Product version)
5. Check if the connector was installed properly. In openIDM console run following command:

   scr list

   among the all installed modules you should see (number can differ):
   [ 24] [active ] org.forgerock.openidm.provisioner.openicf
   see the content of this connector by:

   scr info 24

   (use the number from your list)

   and you should see the content of connector.

6. Now, you need to create sync.json where you define mappings of various attributes and behavior during reconciliation. A simple sync.json could look like this: sync.json
   After configuring sync.json and placing it to conf/ directory the system should be ready.

Testing the setup

1. Verify installed connectors (following command has to be on one line):

   curl --header "X-OpenIDM-Username: openidm-admin"  
        --header "X-OpenIDM-Password: openidm-admin" 
        --request POST "http://localhost:8080/openidm/  
          system?_action=CREATECONFIGURATION"  
          | python -mjson.tool

   this command lists all installed connectors. In the list you should see an Active Directory connector.
   
   …
   {
   “bundleName”: “ActiveDirectory.Connector”,
   “bundleVersion”: “1.0.0.0″,
   “connectorHostRef”: “dotnet”,
   “connectorName”: “Org.IdentityConnectors.ActiveDirectory.ActiveDirectoryConnector”,
   “displayName”: “Windows Active Directory Connector”
   }
   …
   

2. Running reconciliation (following command has to be on one line):

   $ curl --header "X-OpenIDM-Username: openidm-admin" 
          --header "X-OpenIDM-Password: openidm-admin" 
          --request POST "http://localhost:8080/openidm/recon?_action=recon&
            mapping=systemADAccounts_managedUser"

   and as result you should get reconciliation id.
   {“_id”:”0629d920-e29f-4650-889f-4423632481ad”}

3. Check in OpenIDM internal repository (OrientDB or MySQL) if the users were reconciled. How to connect to repo is described here (OrientDB) or here (MySQL).
   Here is an example of output from OrientDB after reconciling. The red marked user has been reconciled from Active Directory.

The test

OpenDJ inherited it’s framework from the OpenDS days which means the old documentation still provides valid guidelines and tips on how to get started with your own unit tests. It would help you get familiar with the utility classes you can use to make your test execution easier. The most relevant documents are:

• Tips And Tricks For Writing Unit Tests
• OpenDS Unit Test Instructions

http://sources.forgerock.org/browse/opendj/trunk/opends/tests/unit-tests-testng/src/server/org/opends/server/plugins

The environment

Before you start working on your tests, you have to check out the OpenDJ source file tree. Say, you are developing a plugin for the 2.4 branch, so you would need the latest stable release:

mkdir opendj-dev
cd opendj-dev
svn co https://svn.forgerock.org/opendj/branches/b2.4/
cd b2.4

Now, your tests should go to:  ‘tests/unit-testing/src/server/<package>/<unit test Java class>’ where:

• <package> is the package which your plugin belongs to, and
• <unit test Java class> is the Java class that implements the unit test(s).

For example, let’s assume we have a plugin called ‘example plugin’ and we made put it in the ‘com.example.plugins’ package (‘com.example.pluginsExamplePlugin). The path would be, say: ‘tests/unit-testing/src/server/com/example/plugins/ExamplePluginTestCase.java’.

Given that your plugin is built separately from the OpenDJ sources, and that the execution of the unit test requires OpenDJ server to be running, you have to make your plugin available to the built-in test instance (and not just the plugin, but also all the libraries you plugin depends on, schema files, etc.). For that to work you need to do the following:

• create a directory: ‘lib/extensions’;
• copy your plugin JAR (and the dependencies) to the following locations: ‘lib’ and ‘lib/extensions’;
• copy your schema file to: ‘resources/schema’.

You should be ready to execute your tests using:

./build.sh test -Dtest.classes=<your unit test>

If we take our ‘example plugin’, you would do the following:

# let’s assume you are located in opendj-dev/b2.4

mkdir lib/extensions

cp <path to>/example-plugin.jar lib

cp <path to>/example-plugin.jar lib/extensions

cp <path to>/99-example-plugin.ldif resources/schema

./build.sh test -Dtest.classes=com.example.plugins.ExamplePluginTestCase

Testing and Maven

As previously mentioned, the testing framework of OpenDJ is very tightly integrated with the build process and makes it unavailable to the other frameworks and tools such as Maven.  If you have chosen Maven to develop your plugin, you will not be able to execute unit tests using OpenDJ tools and the workaround is to follow the guide above

Maven greatly reduces the effort in the process of development, and the archetype is a step furthere in that direction. What OpenDJ plugin archetype offers is a project template with the necessary tools to focus on the implementation of the funcionality rather then wasting time and resources in managing the build framework. In other words, the plugin archetype does for you most of the tasks outlined in the article “OpenDJ plugin development based on example-plugin“.

Download and installation

The archetype is currently in development and it is not available from the online repository (ForgeRock or otherwise). However, the latest version can be downloaded from: here. The downloaded JAR of the archetype has to be deployed in the local repository before you can use it. To do so, you need to execute the following:

mvn install:install-file \

-Dfile=opendj-server-plugin-archetype-1.0.0-SNAPSHOT.jar \

-DgroupId=org.forgerock.opendj \

-DartifactId=opendj-server-plugin-archetype \

-Dpackaging=jar \

-Dversion=1.0.0-SNAPSHOT -DgeneratePom=true

File is the path to the JAR file, and the rest of the parameters should be left as such.

The first step is to create a project for your plugin, let’s call it Sample Plugin:

mvn archetype:generate \

-DarchetypeCatalog=local \

-DarchetypeArtifactId=opendj-server-plugin-archetype \

-DarchetypeGroupId=org.forgerock.opendj \

-DarchetypeVersion=1.0.0-SNAPSHOT \

-DgroupId=com.example -DartifactId=sample-plugin \

-Dversion=1.0.0-SNAPSHOT -DmessageFile=sample_plugin \

-DpluginName=SamplePlugin

Here is the overview of the parameters:

• archetypeCatalog=local specifies that the archetype should be looked for in the local repository;
• archetypeArtifactId=opendj-server-plugin-archetype is the ID of the archetype in the catalog;
• archetypeGroupId=org.forgerock.opendj is the group ID of the archetype;
• groupId=com.example is the package to which this plugin belongs to, typically you want this for your own company;
• artifactId=sample-plugin is the name of the artifact, normally it is lower case name of the plugin where spaces are substituted with ‘-’ sign;
• version=1.0-SNAPSHOT is the version your plugin;
• messageFile=sample_plugin is the name of the file which stores localised messages for the plugin, it should be the lower case version of the plugin name where the space is substituted with the ‘_’ sign – very similar to the artifactId property;
• pluginName=SamplePlugin is the name of the plugin which would be used to generate the template Java class and plugin configuration in XML, it should be the camel-case version of the plugin, without spaces.

This would create a directory which corresponds with the value of artifactIdproperty, in our case: sample-plugin. The directory would be provisioned with the necessary files to produce a working plugin, and the most relevant are:

pom.xml

src/main/java/com/example/messages/sample_plugin.properties

src/main/java/com/example/SamplePlugin.java

src/main/java/com/example/SamplePluginConfiguration.xml

src/main/xml

pom.xml defines the project dependencies and all the phases of the build process. Of course, if your plugin implementation requires additional dependencies, processing and so on, you would want to edit this file accordingly.

src/main/java directory contains the package with the Java classes that implement the functionality of the plugin. The package name corresponds to the groupId property, and the files to the messageFile and pluginName properties as explained above. By default, files that are generated contain the code, the configuration and the messages of the example plugin. You may choose to edit those files or simply get rid of them and use them as an example.

src/main/xml contains XML framework for processing the plugin configuration and generating the Java code for OpenDJ management infrastructure. Normally, no modifications are required here and if you do modify something, it is very likely something would break. From this point forward, you can start modifying the sources with your own functionality.

In order to generate the plugin it is sufficient to execute:

mvn package

It would perform the necessary transformations, get the dependencies and generate the plugin JAR. The only thing it does not create is the schema file, which you have to write by hand according to the configuration of the plugin. For more details please refer to the article “OpenDJ plugin development based on example-plugin“.

Limitations

The archetype currently has several limitations:

• it cannot generate schema automatically;
• it cannot execute unit tests with OpenDJ testing tools.

Todo

For the future versions, it is planned to solve the issues listed in the limitations section and to add the capability to generate javadocs.

References

Discussion on OpenDJ-dev mailing list.

Maven tips and tricks for OpenDJ.

Extending OpenDJ functionality with a plugin.

The problem

In order to have Windows PCs authenticated against Samba, it has to use encoding algorithms specified by Microsoft standards to store the password hashes. For that purpose, it uses two attributes: “sambaLMPassword” and “sambaNTPassword”. On the other hand, an LDAP directory server would normally use “userPassword” attribute to store it’s own password hash (which, by the way, is usually not according to the Microsoft world).

This situation brings about the issue of password synchronisation between the “userPassword” and Samba password attributes. Although Samba provides a feature to synchronise the Samba password with the LDAP password, it does not work in the opposite direction – when the password is changed though the LDAP, the Samba password attributes remain unchanged.

Solution to this problem can be achieved with a plug-in which intercepts the password changes and synchronises the attributes with appropriate values.

The plug-in

OpenDJ has been designed to be highly extensible, so that virtually every aspect of the way it works could be customised. It also comes with an example plug-in which can serve as a good starting basis for development.

Our plug-in covers the following use cases:

• the user password is changed using LDAP modify operation (replace change type on “userPassword” or delete and add change on “userPassword”), and
• the user password is changed using Password Modify Extended Operation.

The basic set-up for OpenDJ integration with Samba is available on the OpenDS wiki page -” Samba as Primary Domain Controler”. Please note that those are basic instructions for a quick set-up and it might not be appropriate for the production use. For the production, make sure you completely understand both products and how to configure them properly to fir your environment. Among other things, consider using a dedicated user instead of “cn=Directory Manager” as noted above.

The installation of the plug-in requires the following steps:

1. copy the JAR file to the OpenDJ directory tree;
2. install the plug-in schema;
3. restart the directory, and
4. configure the plug-in.

dsconfig -X create-plugin -D "cn=directory manager" \
-w <password> -h localhost \
--plugin-name "Samba Password Synchronisation" \
--type samba-password --set enabled:true \
--set samba-oc:sambaSAMAccount

dsconfig -X -n create-debug-target -D "cn=directory manager" \
-w <password> -h localhost --publisher-name "File-Based Debug Logger" \
--target-name cz.profiq.opendj.plugins.SambaPasswordPlugin \
--set debug-level:all

dsconfig -X -n set-log-publisher-prop -D "cn=directory manager" \
-w <password> -h localhost --publisher-name "File-Based Debug Logger" \
--set enabled:true

The starting point for documentation is:

• Extending OpenDS Functionality With a Plug-In

• OpenDJ server API

You should read the first document listed and try to understand it before you start developing your own plugin, otherwise the rest of the article would not make much sense.

Files, naming and dependencies

The good base to start developing your own extension is the example plugin delivered in the OpenDJ binary distribution as example-plugin.zip. You can start by unzipping it and renaming the folder to your custom name. This is a good moment to think about the name of the plugin since it affects the way supporting classes are generated. Although the folder name has no effect, you would normally use the same name on multiple places in the sources. The name ‘example-plugin’ would generate classes with name ‘ExamplePlugin*’, ‘my-custom-plugin’ would result in ‘MyCustomPlugin*’, while ‘mycustom-plugin’ would turn out to be ‘MycustomPlugin*’ – obviously, the ‘-’ sign would cause the class names to be generated with camel case and the framework would require the class names to follow the case in order to compile them. The most important thing here is to pick a name and stick to it.

unzip example-plugin.zip
mv example-plugin my-plugin

The plugin generation framework depends on Xalan-Java as a workaround for a JDK-related XML processing bug, hence you should download the latest distribution of it and unpack it to the ext/ folder as xalan-j since that’s what build.xml expects to find.

unzip -d my-plugin/ext xalan-j*.zip
cd my-plugin/ext
mv xalan-j* xalan-j

Apart from Xalan-Java, the build framework depends on ant-contrib tasks which you have to download and deploy inside the folder where ant would find it (or specify the location with the ant command line parameters).

Next step could be to modify build.xml so it fits the purpose of your custom plugin. The properties to change could be:

• name under project tag
• <description> tag
• pkg.name
• pkg.description

Sources are inside the src/ folder followed by the folders which mark the package name, as usual. You might want to rename the com.example.opends to something more fitting to your company or project. In resource/ folder you would find schema/ and messages/ relevant. The schema file in schema/ folder should follow the name you have chosen in the form ’99-NAME.ldif’, for example: ’99-my-example-plugin.ldif’ – although this would not impact the building process, the naming would be consistent. The messages/ directory contains the properties file(s) with the error messages and their localisation organised in the folders that follow the name of the package. Again, another part which should be renamed following the chosen name.

Note that resources/ folder contains config/ which in turn has a file with LDIF representation of the configuration defined in the XML file. That file (and folder for that matter) is not needed contrary to what README file says. Previously this file was used to configure the plugin by injecting it to the config.ldif file, but as the software evolved, this step is now performed with the dsconfig command. More about that later.

You will find your development process bouncing between the: source files which implement the plugin functionality, the configuration file for the plugin which is used to generate dependent classes, the properties file which defines the messages and, to smaller extent, the schema file.

The files we find in the sources folder of the example plugin are: ExamplePlugin.java, ExamplePluginConfiguration.xml, Package.xml and package-info.java. ‘ExamplePlugin*’ files are the ones that should be renamed to match the name you have chosen, say, if you have chosen ‘my-example-plugin’ then they should be: MyExamplePlugin.java and MyExamplePluginConfiguration.xml. Next, you should modify MyExamplePluginConfiguration.xml not only to match your configuration needs but also your naming choice (‘name’ property, ‘package’ property, etc.). Based on the information in the configuration file, the build framework would generate classes in src-generated/ folder which would follow the names and packages properties, so if you do not name everything consistently and refer to it in your sources, the compilation process would fail. Needless to say, the contents of Packages.xml should match the rest of the configuration.

The relationship of the most important files is the following:

• src/com/example/opends/ExamplePlugin.java contains the functionality of the plugin;
• src/com/example/opends/ExamplePluginConfiguration.xml defines the configuration parameters for the plugin (set with the dsconfig command) which can be accessed via ‘config’ object inside the code;
• resources/messages/com/example/opends/messages/example_plugin.properties defines the localised messages (for the given locale) which can be accessed from the code in a generic way, and
• resources/schema/99-example-plugin.ldif is the schema definition for the parameters defined in the configuration file.

As you develop the functionality of the plugin, you will find it necessary to update the configuration and/or the messages which would require you re-generate the dependant files, otherwise if you use an IDE for development, the changes would not be reflected.

Notes on the configuration

The configuration parameters defined in the configuration file are represented in the directory as LDAP entries, hence when you define new parameters you are really defining new object class and new attributes. Logically, in order to have the directory updated with the plugin configuration, it has to contain the schema with the definition of the object classes and attributes you want to add. The parameters need not be reflected in the schema files during the time of development – it is only important to update it before you install the plugin, as the schema definition is important for the directory server to be able to create the plugin and create it’s configuration.

To get the better idea of how to set up the schema file, you can compare the ExamplePluginConfiguration.xml with 99-example-plugin.ldif. Another helpful example might be found in the Samba password syncronisation plugin: SambaPasswordPluginConfiguration.xml, 99-samba-password-plugin.ldif.

Creating a NetBeans project

If you want to develop your plugin as a NetBeans project, here is a simple way to do it:

1. click on the New Project button;
2. choose Java Free-form Project from the Java category;
3. set the Location to the folder of your plugin;
4. click Next
5. click Next
6. uncheck Separate Classpath…, and add OpenDJ.jar
7. click Finish

This configuration would relay on the existing build.xml script to build everything, so you might want to update the menu with relevant targets such as compileadmin, generate-messages, package, install, etc.

Compiling and installing

If your code relies on external libraries, such as OpenDJ SDK, they should go to the ext/ directory.

The most relevant ant targets are:

• compileadmin - generates the dependent classes (based on the XML file);
• generate-messages – generates the messages (based on the properties file);
• compile/package – compiles the sources/creates the jar ready to install, and
• install – installs the plugin

Installation of the plugin is not a single step which depends on the ant target, but requires various actions. Running the install target with ant would copy the plugin JAR, the schema and the configuration LDIF to the relevant folders under the location specified by the opends.install.dir property in build.xml (respectively, by default: ../lib/extensions, ../config). As noted previously, the configuration LDIF is obsolete and should be removed so that it is not copied at all. The external libraries would not be copied (you would have to do that by hand), and the installation would have effect only upon the restart. Startup messages would indicate if the plugin was loaded and if there were any errors with the schema file.

The installation does not end here as the plugin has to be registered, configured and enabled in order to be used. All of that can be done in a single line with the dsconfig tool. For example:

dsconfig -X -n create-plugin --plugin-name "My Example Plugin" \
--type my-example-plugin --set enabled:true --set some-property:value

Debugging

Most of the time, when a problem occurs, you would want to know what is happening inside your code. For this purpose you can define a debug logger and log whatever you find useful. To do that, you should create a DebugTracer object as a static member of your class:

  private static final DebugTracer TRACER = DebugLogger.getTracer();

The messages logged with the TRACER need debugging to be enabled in the directory and you can do that with the dsconfig command:

• create the debug target:

dsconfig -X -n create-debug-target \
--publisher-name "File-Based Debug Logger" \
--target-name com.example.opends.ExamplePlugin --set debug-level:all

• enable the debug log:

dsconfig -X -n set-log-publisher-prop \
--publisher-name "File-Based Debug Logger" --set enabled:true

Easier way

Although still work in progress, Maven archetype for OpenDJ plugins is an easier alternative. It will perform all the steps necessary to keep you focused on coding and less on the internal dependencies of the example plugin.

Useful resources

• Samba password synchronization plugin sources
• OpenDJ SDK
• OpenDJ sources

Web Interface set-up

OpenDJ, formerly known as OpenDS is a full implementation of the LDAP version 3 which is also supported by Liferay as a client. Hence, the integration as a generic LDAP service is rather trivial if performed via Web interface:

• we need to log in as the administrator and open the Control Panel in the Manage drop-down menu;
• we choose the Settings option within the Portal section;
• here, on the left side, under Configuration options, we chose Authentication, and finally LDAP;
• we Add the server;
• name parameter identifies this particular server instance;
• Other Directory Server should be selected as a generic LDAP server.

• Base Provider URL represents the server host and port in the URI syntax;
• Base DN is the starting point in the tree where all the searches should start from;
• Principal is the user which Liferay uses to connect to the directory and perform required operations;
• Credentials is the password of the principal.

• Authentication Search Filter is the filter Liferay would use to search for the Liferay users (hoovering over the question mark gives more information on the type of variables that could be used to perform the mapping of Liferay fields to LDAP attributes);
• Import Search Filter is used to identify the LDAP entries to be imported to Liferay user database, if the import option has been set to true;
• Screen Name is the LDAP attribute which will be used for the value of Liferay screen name, by defualt it is “cn” but it could also be “uid”, depending on your directory design;
• Password is the LDAP attribute which holds the user password hash, default is “userPassword” which is also the default value for OpenDJ;
• E-mail Address is the LDAP attribute for the e-mail address, by default “mail”;
• Full Name is the LDAP attribute for the full name of the user, by default it is empty, but typically it is “cn”;
• First Name is the LDAP attribute for the first name of the user, by default it is “givenName”;
• Middle Name is the LDAP attribute for the given name, by default it is empty;
• Last Name is the LDAP attribute for the last name, by default it is “sn”;
• Job Title is the LDAP attribute for the job title, by default it is “title”;
• Group Membership is the LDAP attribute which lists the groups which the user belongs to, in OpenDJ this should be set to the operational attribute “isMemberOf”.

OpenDJ and OpenDS are essentially the same product which was developed by the same people who developed the original SJS Directory Server. As of the Oracle-Sun merger, the development team moved on to ForgeRock where they keep the development active. Although the maturity level of the product is quite high, the amount of information around it is not sufficient. Our goal at profiq is to start a series of articles on different aspects of integration of OpenDJ with other popular open source products and rise the awareness of this great product.