Tutorial - LDAP Synchronization Provider Example

Motivation

With the help of SPI synchronization, you have the option to perform the following actions against arbitrary external repositories, which otherwise would have to be performed against audit trail databases:

You need to perform the following steps to make SPI synchronizing possible:

  1. Create a data structure, where the required information should be stored. Please refer to section LDAP Directory Structure for details.
  2. Configure an external repository, against which the actions mentioned above should be performed. Please refer to the sections LDAP Configuration (OpenLDAP) and Setting Up the LDAP Browser - Optional accordingly.
  3. Set up a working environment as described in the Infinity Process Platform Installation Guide.
  4. SPI implementation. Please refer to the section Implementing SPI.
  5. Configuration of Infinity Process Platform. Please refer to the section Infinity Process Platform Configuration for details.

LDAP Directory Structure

You can download the following zip file containing sources required for this tutorial:

You find all data needed for this tutorial, like user and department information and grants, in LDIF (LDAP Data Interchange Format) format in the user-directory.ldif file, residing in the examples/ldap-sync/etc folder of this zip file. Please note that user groups are not covered with this example.

Branch Nodes

ou=People

ou=People contains user information like user name (uid), password (userPassword), name and last name (givenName and sn), etc.

# People
dn: ou=People,dc=ldap,dc=example,dc=ipp
objectClass: top
objectClass: organizationalUnit
ou: People

ou=Departments

ou=Departments contains information about the department (ou) and the according description.

# Departments
dn: ou=Departments,dc=ldap,dc=example,dc=ipp
objectClass: top
objectClass: organizationalUnit
ou: Departments

ou=Groups

ou=Groups represents the grants by assigning an organization, a role or department to a user (uniqueMember). Roles and organizations (cn) are defined in the model, whereby departments are defined in the LDAP folder under ou=Departments.

# Groups
dn: ou=Groups,dc=ldap,dc=example,dc=ipp
objectClass: top
objectClass: organizationalUnit
ou: Groups

LDAP Configuration

To configure the LDAP, perform the following steps:

  1. Install the LDAP server from www.openldap.org.
  2. Add the following content to the LDAP configuration file slapd.conf:
    ucdata-path	./ucdata
    include		./schema/core.schema
    include		./schema/cosine.schema
    include		./schema/inetorgperson.schema
    
    pidfile		./run/slapd.pid
    argsfile	./run/slapd.args
    
    database	bdb
    suffix		"dc=ldap,dc=example,dc=ipp"
    rootdn		"cn=Manager,dc=ldap,dc=example,dc=ipp"
    rootpw		secret
    
    directory	./data
    index		objectClass	eq
    
  3. Make sure the LDAP configuration file ldap.conf is empty.
  4. Make sure the LDAP server is running (e.g. LDAP Windows service is started).
  5. Import the files necessary for this tutorial (user and department information as well as grants) via the follwing console command:
    %OPEN_LDAP_DIR%/ldapadd -f %CARNOT_HOME%/examples/ldap-sync/etc/user-directory.ldif -D "cn=Manager,dc=ldap,dc=example,dc=ipp" -x -w secret

Setting Up the LDAP Browser (Optional)

To set up the LDAP browser, perform the following steps:

  1. Install the LDAP browser, you like to visualize an LDAP structure with, from http://www.ldapbrowser.com/.
  2. Start the LDAP browser.
  3. Select File > New Profile.
  4. After the data import to the LDAP directory, the LDAP browser displays the following:

    LDAP Browser
    Figure: Data displayed in the LDAP Browser

Implementing SPI

It is necessary to supplement the following abstract classes and interfaces to provide the implementations needed to access the desired external repository:

Please refer to the chapter Integrating External User Repositories for detailed information on these classes and interfaces.

Additionally, the following abstract classes have to be supplemented with the necessary implementation, so that they are able to get the information on user, user group and department retrieved from the external repository:

You find a sample SPI implementation in the Examples section of your Infinity Process Platform installation. Download the following file containing the example implementation:

In this example, the class LDAPAdapter plays a major role as it converts the Java requests into LDAP requests (please see the following section). Hereby it is using the class LDAPConnection, which encapsulates the connection to an LDAP directory structure.

In the following section, we provide a quick look into the necessary implementations:

To keep the search in the LDAP directory flexible, the search mechanism is implemented via filter, which is demonstrated in the following user filter:

  1. Starting with the filter declared in the carnot.properties file
    (Property LDAPSynchronization.UserFilter)(&(uid=%v)(objectclass=inetorgperson)) ...
  2. ... the placeholder %v is replaced with exactly the user, which is searched for, e.g. motu:
    &(uid=motu)(objectclass=inetorgperson)
    Hereby, the character & describes the logical conjunction operator. The two following conditions in the brackets have to be fulfilled.
  3. It is also possible to restrict the search scope via the property LDAPSynchronization.UserBaseDN, which is given relativ to the base DN: ou=People.
  4. In summary a search request results, comparable to the following OpenLDAP request on the console:
    %OPEN_LDAP_HOME%/ldapsearch -b "ou=People,dc=ldap,dc=example,dc=ipp" "(&(uid=motu)(objectclass=inetorgperson))"

Additionally to the configurable filters, there are numerous further properties, which can be configured with the help of the carnot.properties file, e.g. the attribute names of the several LDAP entries or the LDAP entry, which is determined to be searched for users (see class LDAPProperties).

Infinity Process Platform Configuration

The following properties have to be added to your carnot.properties file:

Security.Authentication.LoginService = org.eclipse.stardust.examples.authorization.ldap.LDAPLoginProvider

Security.Authorization.SynchronizationProvider = org.eclipse.stardust.examples.authorization.ldap.LDAPSynchronizationProvider
Security.Authorization.SynchronizationStrategy = org.eclipse.stardust.examples.authorization.ldap.AlwaysSyncStrategy

Security.Authentication.Mode = external
Security.Authorization.Mode = principal

LDAPSynchronization.ServerName = localhost
LDAPSynchronization.ServerPort = 389

LDAPSynchronization.BindMode = dedicated
LDAPSynchronization.BindUserDN = cn=Manager,dc=ldap,dc=example,dc=ipp
LDAPSynchronization.BindPassword = secret

LDAPSynchronization.RootDN = dc=ldap,dc=example,dc=ipp
LDAPSynchronization.UserBaseDN = ou=People
LDAPSynchronization.DepartmentBaseDN = ou=Departments
LDAPSynchronization.GroupBaseDN = ou=Groups

LDAPSynchronization.UserFilter = (&(uid=%v)(objectclass=inetorgperson))
LDAPSynchronization.DepartmentFilter = (&(cn=%v)(objectClass=organizationalRole))
LDAPSynchronization.ParticipantFilter = (&(uniqueMember=uid=%v,ou=People,dc=ldap,dc=example,dc=ipp)(objectClass=groupOfUniqueNames))