Configuring JBoss with PicketBox LDAP Module

In this tutorial we will show how to connect WildFly / JBoss EAP to OpenLDAP directory service using PicketBox Security Framework. For a more recent configuration (using Elytron) we recommend checking this article: How to configure an Elytron LDAP Realm on WildFly

Installing LDAP

OpenLDAP is a free suite of client and server tools that implement the Lightweight Directory Access Protocol (LDAP) for Linux/Windows. Strictly speaking, though, LDAP isn’t a database at all, but a protocol used to access information stored in an information directory (also known as an LDAP directory).
OpenLDAP is available at
If you are looking for a Windows version, you can find it here:

OpenLDAP installation guide for Linux can be found here: (Windows users can simply execute the OpenldapforWindows.exe which will guide you through an intuitive wizard.)

Once installed open the slapd.conf file and let’s customize the top level of the LDAP directory tree. In particular we will change the domain component (dc) to (replace it with your actual domain).

suffix        "dc=acme,dc=com"
rootdn        "cn=Manager,dc=acme,dc=com"

Once done with it, you can start LDAP using:

su root -c /usr/local/libexec/slapd  # Linux

slapd.exe # Windows

Now in order to connect LDAP with JBoss AS, you need to define one user and assign it to one role. For this purpose we will create one user named admin and assign it to the role Manager.

In this tutorial we have used the free tool JXExplorer to connect to OpenLDAP and load the ldif file.

dn: dc=acme,dc=com
objectclass: top
objectclass: dcObject
objectclass: organization
dc: acme
o: MCC

dn: ou=People,dc=acme,dc=com
objectclass: top
objectclass: organizationalUnit
ou: People

dn: uid=admin,ou=People,dc=acme,dc=com
objectclass: top
objectclass: uidObject
objectclass: person
uid: admin
cn: Manager
sn: Manager
userPassword: secret

dn: ou=Roles,dc=acme,dc=com
objectclass: top
objectclass: organizationalUnit
ou: Roles

dn: cn=Manager,ou=Roles,dc=acme,dc=com
objectClass: top
objectClass: groupOfNames
cn: Manager
description: the acmeAS7 group
member: uid=admin,ou=People,dc=acme,dc=com

Once loaded the LDIF file, try reconnecting to OpenLDAP using the following credentials:

jboss ldap tutorial

You should see the following directory structure, containing one user (admin) and one role (Manager):

ldap tutorial jboss wildfly

Configuring JBoss LDAPAuth

Next, to use LDAP for Authentication, you can use the LdapExtended Login module, entering the values of the bindDN and bindCredential contained in slapd.conf. You need to specify as well which organization unit contains the users, through the baseCtxDN option and as well the organization which contains the roles through the rolesCtxDN. Additionally you need to specify the following properties:
The baseFilter option is a search filter used to locate the context of the user to authenticate.
The roleFilter is as well a search filter used to locate the roles associated with the authenticated user.
The searchScope sets the search scope to one of the strings. ONELEVEL_SCOPE searches directly under the named roles context.
Finally the allowEmptyPasswords: It is a flag indicating if empty(length==0) passwords should be passed to the LDAP server.

Here’s the configuration to be added as security-domain for a JBoss AS 7 / JBoss EAP 6 installation:

<security-domain name="LDAPAuth">
      <login-module code="LdapExtended" flag="required">
        <module-option name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
        <module-option name="java.naming.provider.url" value="ldap://localhost:389"/>
        <module-option name="" value="simple"/>
        <module-option name="bindDN" value="uid=admin,dc=acme,dc=com"/>
        <module-option name="bindCredential" value="secret"/>
        <module-option name="baseCtxDN" value="ou=People,dc=acme,dc=com"/>
        <module-option name="baseFilter" value="(uid={0})"/>
        <module-option name="rolesCtxDN" value="ou=Roles,dc=acme,dc=com"/>
        <module-option name="roleFilter" value="(member={1})"/>
        <module-option name="roleAttributeID" value="cn"/>
        <module-option name="searchScope" value="ONELEVEL_SCOPE"/>
        <module-option name="allowEmptyPasswords" value="true"/>

If you are running a JBoss 4/5/6 security domain, here’s the corresponding configuration:

<application-policy name="LDAPAuth">
      <login-module code="" flag="required" >
         <module-option name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</module-option>
         <module-option name="java.naming.provider.url">ldap://localhost:389</module-option>
         <module-option name="">simple</module-option>
         <module-option name="bindDN">uid=admin,dc=acme,dc=com</module-option>
         <module-option name="bindCredential">secret</module-option>
         <module-option name="baseCtxDN">ou=People,dc=acme,dc=com</module-option>
         <module-option name="baseFilter">(uid={0})</module-option>

         <module-option name="rolesCtxDN">ou=Roles,dc=acme,dc=com</module-option>
         <module-option name="roleFilter">(member={1})</module-option>
         <module-option name="roleAttributeID">cn</module-option>
         <module-option name="searchScope">ONELEVEL_SCOPE</module-option>
         <module-option name="allowEmptyPasswords">true</module-option>

Done with the application server configuration, last step will be enabling security at application level; supposing you are going to secure a web application, the first step will be declaring the protected resources in your web.xml file, which are allowed just to the Manager role:

<web-app xmlns:xsi=""
    xmlns="" xmlns:web=""
    id="WebApp_ID" version="3.0">

            <description>application security constraints
        <realm-name>LDAPAuth realm</realm-name>

And here the jboss-web.xml configuration file which links the application to the LDAPAuth security domain. This file needs to be placed into the WEB-INF folder of your web application:


Found the article helpful? if so please follow us on Socials