8.4. Enable LDAP Authentication in the OSGi Container

Overview

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

To enable LDAP authentication in a standalone OSGi container:

Ensure that the X.500 directory server is running.
Start Red Hat JBoss A-MQ by entering the following command in a terminal window:
```
amq
```
Create a Blueprint configuration file called ldap-module.xml.

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>

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).

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

To enable LDAP authentication in a Fabric (affecting all of the containers in the current fabric):

Ensure that the X.500 directory server is running.
If your local Fabric container is not already running, start it now, by entering the following command in a terminal window:
```
./amq
```
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.
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
```
Note
In effect, this command creates a new branch named 1.1 in the Git repository underlying the ZooKeeper registry.
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
```
The built-in profile editor opens automatically, which you can use to edit the contents of the ldap-module.xml resource.
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>
```
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).
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
```
The built-in profile editor opens automatically. Add the following line to the agent properties:
```
bundle.ldap-realm=blueprint:profile:ldap-module.xml
```
Save and close the agent properties by typing Ctrl-S and Ctrl-X.
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
```
To activate LDAP on all containers in the fabric, enter the following console command:
```
JBossFuse:karaf@root> container-upgrade --all 1.1
```
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

Test the new LDAP realm by connecting to the running container using the Red Hat JBoss A-MQ client utility, as follows:

Open a new command prompt.
change directory to the JBoss A-MQ InstallDir/bin directory.
Enter the following command to log on to the running container instance using the identity janedoe:
```
client -u janedoe -p secret
```
You should receive the following message:
```
Authentication failure
```
This fails because janedoe does not have the admin role which is required for using the remote console.
Enter the following command to log on to the running container instance using the identity jdoe:
```
client -u jdoe -p secret
```
You should successfully log into the container's remote console because jdoe does have the admin role.
Log off the remote console by entering the logout command.

8.4. Enable LDAP Authentication in the OSGi Container

Overview

Procedure for standalone OSGi container

Procedure for a Fabric

Test the LDAP authentication

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links