Configure JBoss with LDAP

In this tutorial we will show how to connect JBoss AS 7 (and earlier AS releases too) to OpenLDAP directory service.

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 jboss ldap tutorial jboss ldap tutorial
You should see the following directory structure, containing one user (admin) and one role (Manager):

jboss ldap tutorial openldap jboss example howto



Now in order 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 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’s 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: