Red Hat JBOSS Data Grid

Expanding on Tristan's blog, where he spoke of enabling security for JBoss Data Grid caches, in this post we will cover how to add LDAP based security to the JDG caches. The principles and techniques remain defined by Tristan, but there are some minor changes that I will be highlighting in this blog for a successful working configuration of JDG enabled with LDAP security.

Before we jump on to configuring the JDG for security, I would like to brush up on the available permissions in JDG:

  • READ - typical read operations get, contains etc., except bulk read
  • WRITE - typical write operations put, putIfAbsent, replace, remove, evict
  • EXEC - distexec, mapreduce
  • LISTEN - permissions to add Listeners
  • BULK_READ - keySet, values, query, entrySet etc.,
  • BULK_WRITE - clear, putAll
  • ALL_READ - all read operations typically READ + BULK_READ
  • ALL_WRITE - all write operations typically WRITE + BULK_WRITE
  • LIFECYCLE - start/stop of caches
  • ADMIN - typical cache administration operations like getVersion, getCacheConfiguration etc.,
  • ALL -  All the permissions listed above

More information on these is available in the JDG Developer Guide.



The complete source code of examples used in this blog is available on Github, here. If you don't have an LDAP server running on your machine and wish to quickly run one, you can do so by pulling a docker image of the same by pulling docker image fabric8/389dsto run a 389ds-Directory Server with sample users and groups as shown in LDIF, run the following command,

docker run -d --name "dirsrv-389ds" -p 10389:389 fabric8/389ds -e "DIRSRV_ADMIN_USERNAME=admin,DIRSRV_ADMIN_PASSWORD=admin@123, DIRSRV_MANAGER_PASSWORD=admin@123, DIRSRV_SUFFIX=dc=example,dc=com"

Groups and Permissions

The following section shows the Groups and Roles mapping, refer to JDG Security Permissions for more information on each of the permissions mentioned below:

  • ClusterAdmins - the user(s) belonging to this group can do ALL operations on JDG cache(s)
  • Managers - the users(s) belonging to this group can do ALL_READ,ALL_WRITE,EXEC on JDG cache(s)
  • Developers - the user(s) belonging to this group can only WRITE on JDG cache(s)
  • Business - the user(s) belonging to this group can only READ on JDG cache(s)

If you are running the dockerized version of the 389ds then all the required groups mentioned above with sample users are all set up, if you are using your own LDAP server then you'll import the LDIF to have them created for you.

Configuring JDG

We leverage the jboss-cli for setting up the LDAP security and configuring the authentication and authorization JDG. The source repo's jboss-cli folder has the following JBOSS CLI commands file, which can help in setting up the LDAP Security and JDG Cache security.


  • JDG Server is up and running with "clustered.xml" as configuration and its management port is on 9990, if you don't have JDG running you can download it from here, unzip it to a folder of your choice and then start it with the command,
    $JBOSS_HOME/bin/ -c clustered.xml
  • Export JBOSS_HOME environment variable to point to JDG Home, this not a must but a convenience to run the JBOSS CLI commands.

Before getting started, clone the repository to a folder of your choice, let's call it as $PROJECT_HOME and then change to directory jdg-security-demo under $PROJECT_HOME, unless explicitly stated, all the commands in the following sections will be executed from $PROJECT_HOME/jdg-security-demo directory.

JDG LDAP Security Configuration

  • To configure LDAP security, run the following command,
$JBOSS_HOME/bin/ --controller= --connect --file=./jboss-cli/ldap-enable.cli

NOTE: You might need to check the ./jboss-cli/ldap-enable.cli for ports, LDAP credentials etc., corresponding to your LDAP server before running the above command.

  • After running the above command the server restart, wait for the server to restart completely.
  • Now execute,
$JBOSS_HOME/bin/ --controller= --connect

It will prompt you for a username and password, you can use any of the usernames from LDAP with this demo, the application is not configured for authorization or management. If you have imported the LDIF then you can use admin/password to log into the JBoss CLI, if you are successfully logged in then LDAP security is configured correctly. Going forward every subsequent connection via JBoss CLI will prompt for the username and password.

JDG Cache Security Configuration

  • To configure JDG security do run the following command,
$JBOSS_HOME/bin/ --controller= --connect --file=./jboss-cli/jdg-security-enable.cli
  • The command will add security to the JDG cache container "clustered" with roles and permissions mentioned above, the command will also secure the HotRod connector, hence making the clients pass credentials to do operations on the cache.

Example JDG Cache Configuration

To run the test let's create a sample cache and its configuration, which we secured using the LDAP and authorization previously defined. To create sample cache and configuration run the following command,

$JBOSS_HOME/bin/ --controller= --connect --file=./jboss-cli/cache-security-config.cli

The command above creates a distributed cache configuration called "securedConfig" and creates distributed cache called "users-cache" which will use the "securedConfig".

Testing the Secured Cache

To test the secured cache from the project root run the following command,

mvn clean test

The project has only one test case called org.workspace7.jdg.JDGSecurityTest, which runs a simple test to check all the roles mentioned above.

Couple of points to note in the setup, the "cache-container" security authentication will still use "identity-role-mapper" instead of "common-name-role-mapper", this is a workaround for now until the JDG-951 is fixed, to enable this workaround, map correct role names, the LDAP security authorization should be configured to return SIMPLE names for the roles like shown below,

group-search group-name="SIMPLE" iterative="true" group-dn-attribute="dn" group-name-attribute="cn"
group-to-principal search-by="DISTINGUISHED_NAME" base-dn="ou=Groups,dc=example,dc=com"
membership-filter principal-attribute="uniqueMember"/

Ideally, you don't need to do these updates, as the jboss-cli's that were executed earlier takes care of this workaround. Please refer to the JDG Developer guide for more information on mappers that are available.

That's it! You are all set to rock with JDG enabled with LDAP Authentication/Authorization; you can check the complete clustered.xml sample here.

Click here to download JBoss Data Grid an intelligent, distributed caching solution that boosts application performance and provides greater deployment flexibility.

Last updated: March 21, 2023