Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

8.4. Enable LDAP Authentication in the OSGi Container

Overview
Copy link

In this part of the tutorial you will configure an LDAP realm in the OSGi container. The new realm overrides the default karaf realm, so that the container authenticates credentials based on user entries stored in the X.500 directory server.

Procedure for standalone OSGi container
Copy link

To enable LDAP authentication in a standalone OSGi container:
  1. Ensure that the X.500 directory server is running.
  2. Start Red Hat JBoss A-MQ by entering the following command in a terminal window: 
    amq
    Copy to Clipboard Toggle word wrap
  3. Create a Blueprint configuration file called ldap-module.xml.
  4. Copy Example 8.1, “JAAS Realm for Standalone” into ldap-module.xml.

    Example 8.1. JAAS Realm for Standalone

    <?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
  xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0"
  xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0">

  <jaas:config name="karaf" rank="1">
    <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule"
                 flags="required">
      initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
      connection.username=uid=admin,ou=system
      connection.password=secret
      connection.protocol=
      connection.url=ldap://localhost:10389
      user.base.dn=ou=users,ou=system
      user.filter=(uid=%u)
      user.search.subtree=true
      role.base.dn=ou=roles,ou=system
      role.name.attribute=cn
      role.filter=(member=uid=%u)
      role.search.subtree=true
      authentication=simple
    </jaas:module>
  </jaas:config>
</blueprint>
    Copy to Clipboard Toggle word wrap
    This login module creates a JAAS realm called karaf, which is the same name as the default JAAS realm used by Red Hat JBoss A-MQ. By redefining this realm with a rank attribute value greater than 0, it overrides the standard karaf realm which has the rank 0. For more information on configuring a JAAS realm see Section 2.1.2, “Defining JAAS Realms”.
    For a detailed description of configuring JBoss A-MQ to use LDAP see Section 2.2, “Enabling LDAP Authentication”.
    Important
    When setting the JAAS properties above, do not enclose the property values in double quotes.
    Tip
    If you use OpenLDAP, the syntax of the role filter is (member:=uid=%u).
  5. To deploy the new LDAP module, copy the ldap-module.xml into the JBoss A-MQ deploy/ directory.
    The LDAP module is automatically activated.

Procedure for a Fabric
Copy link

To enable LDAP authentication in a Fabric (affecting all of the containers in the current fabric):
  1. Ensure that the X.500 directory server is running.
  2. If your local Fabric container is not already running, start it now, by entering the following command in a terminal window: 
    ./amq
    Copy to Clipboard Toggle word wrap
    Note
    If the Fabric container you want to connect to is running on a remote host, you can connect to it using the client command-line utility in the InstallDir/bin directory.
  3. Create a new version of the Fabric profile data, by entering the following console command: 
    JBossFuse:karaf@root> version-create
Created version: 1.1 as copy of: 1.0
    Copy to Clipboard Toggle word wrap
    Note
    In effect, this command creates a new branch named 1.1 in the Git repository underlying the ZooKeeper registry.
  4. Create the new profile resource, ldap-module.xml (a Blueprint configuration file), in version 1.1 of the default profile, as follows: 
    JBossFuse:karaf@root> profile-edit --resource ldap-module.xml default 1.1
    Copy to Clipboard Toggle word wrap
    The built-in profile editor opens automatically, which you can use to edit the contents of the ldap-module.xml resource.
  5. Copy Example 8.2, “JAAS Realm for Fabric” into the ldap-module.xml resource, customizing the value of the rank attribute and the connection.url property, as necessary.

    Example 8.2. JAAS Realm for Fabric

    <?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
  xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0"
  xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0">

  <jaas:config name="karaf" rank="2">
    <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule"
                 flags="required">
      initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
      connection.username=uid=admin,ou=system
      connection.password=secret
      connection.protocol=
      connection.url=ldap://LDAPHost:10389
      user.base.dn=ou=users,ou=system
      user.filter=(uid=%u)
      user.search.subtree=true
      role.base.dn=ou=roles,ou=system
      role.name.attribute=cn
      role.filter=(member=uid=%u)
      role.search.subtree=true
      authentication=simple
    </jaas:module>
  </jaas:config>
</blueprint>
    Copy to Clipboard Toggle word wrap
    Where LDAPHost is the name of the host where the LDAP server is running. You must be sure to use a hostname that is accessible to all of the containers in the fabric (for example, you cannot use localhost as the hostname here).
    Save and close the ldap-module.xml resource by typing Ctrl-S and Ctrl-X.
    This login module creates a JAAS realm called karaf, which is the same name as the default JAAS realm used by Red Hat JBoss A-MQ. By redefining this realm with a rank of 2, it overrides all of the previously installed karaf realms. For more information on configuring a JAAS realm see Section 2.1.2, “Defining JAAS Realms”.
    For a detailed description of configuring JBoss A-MQ to use LDAP see Section 2.2, “Enabling LDAP Authentication”.
    Important
    Pay particular attention to the value of the rank to ensure that it is higher than all previously installed karaf realms. If the rank is not sufficiently high, the new realm will not be used by the fabric.
    Important
    When setting the JAAS properties above, do not enclose the property values in double quotes.
    Tip
    If you use OpenLDAP, the syntax of the role filter is (member:=uid=%u).
  6. Edit the agent properties of version 1.1 of the default profile, adding an instruction to deploy the Blueprint resource file defined in the previous step. Enter the following console command: 
    JBossFuse:karaf@root> profile-edit default 1.1
    Copy to Clipboard Toggle word wrap
    The built-in profile editor opens automatically. Add the following line to the agent properties: 
    bundle.ldap-realm=blueprint:profile:ldap-module.xml
    Copy to Clipboard Toggle word wrap
    Save and close the agent properties by typing Ctrl-S and Ctrl-X.
  7. The new LDAP realm is not activated, until you upgrade a container to use the new version, 1.1. To activate LDAP on a single container (for example, on a container called root), enter the following console command: 
    JBossFuse:karaf@root> container-upgrade 1.1 root
    Copy to Clipboard Toggle word wrap
    To activate LDAP on all containers in the fabric, enter the following console command: 
    JBossFuse:karaf@root> container-upgrade --all 1.1
    Copy to Clipboard Toggle word wrap
    Important
    It is advisable to upgrade just a single container initially, to make sure that everything is working properly. This is particularly important, if you have only remote access to the fabric: if you upgrade all of the containers at once, you might not be able to reconnect to the fabric.

Test the LDAP authentication
Copy link

Test the new LDAP realm by connecting to the running container using the Red Hat JBoss A-MQ client utility, as follows:
  1. Open a new command prompt.
  2. change directory to the JBoss A-MQ InstallDir/bin directory.
  3. Enter the following command to log on to the running container instance using the identity janedoe: 
    client -u janedoe -p secret
    Copy to Clipboard Toggle word wrap
    You should receive the following message: 
    Authentication failure
    Copy to Clipboard Toggle word wrap
    This fails because janedoe does not have the admin role which is required for using the remote console.
  4. Enter the following command to log on to the running container instance using the identity jdoe: 
    client -u jdoe -p secret
    Copy to Clipboard Toggle word wrap
    You should successfully log into the container's remote console because jdoe does have the admin role.
  5. Log off the remote console by entering the logout command.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat