9.4. Enable LDAP Authentication in the OSGi Container

Overview

This section explains how to 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.

References

More detailed documentation is available on LDAP authentication, as follows:

Procedure for standalone OSGi container

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
  3. Create a file called ldap-module.xml.
  4. Copy Example 9.1, “JAAS Realm for Standalone” into ldap-module.xml.

    Example 9.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="200">
    <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule"
                 flags="required">
      initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
      connection.url=ldap://Hostname:Port
      connection.username=cn=Directory Manager
      connection.password=LDAPPassword
      connection.protocol=
      user.base.dn=ou=People,dc=localdomain
      user.filter=(&amp;(objectClass=inetOrgPerson)(uid=%u))
      user.search.subtree=true
      role.base.dn=ou=Groups,dc=localdomain
      role.name.attribute=cn
      role.filter=(uniquemember=%fqdn)
      role.search.subtree=true
      authentication=simple
    </jaas:module>
  </jaas:config>
</blueprint>
    You must customize the following settings in the ldap-module.xml file:
    connection.url
    Set this URL to the actual location of your directory server instance. Normally, this URL has the format, ldap://Hostname:Port. For example, the default port for the 389 Directory Server is IP port 389.
    connection.username
    Specifies the username that is used to authenticate the connection to the directory server. For 389 Directory Server, the default is usually cn=Directory Manager.
    connection.password
    Specifies the password part of the credentials for connecting to the directory server.
    authentication
    You can specify either of the following alternatives for the authentication protocol:
    • simple implies that user credentials are supplied and you are obliged to set the connection.username and connection.password options in this case.
    • none implies that authentication is not performed. There is no need to set the connection.username and connection.password options in this case.
    This login module creates a JAAS realm called karaf, which is the same name as the default JAAS realm used by 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 (but note that in the context of Fabric, the default karaf realm has a rank of 99, so you need to define a new realm with rank 100 or greater to override the default realm in a fabric).
    For more details about how to configure JBoss A-MQ to use LDAP, see Section 2.1.7, “JAAS LDAP Login Module”.
    Important
    When setting the JAAS properties above, do not enclose the property values in double quotes.
  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.
    Note
    Subsequently, if you need to undeploy the LDAP module, you can do so by deleting the ldap-module.xml file from the deploy/ directory while the Karaf container is running.

Procedure for a Fabric

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
    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
    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
    The built-in profile editor opens automatically, which you can use to edit the contents of the ldap-module.xml resource.
  5. Copy Example 9.2, “JAAS Realm for Fabric” into the ldap-module.xml resource, customizing the configuration properties, as necessary.

    Example 9.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"
  xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0">

  <command-bundle xmlns="http://karaf.apache.org/xmlns/shell/v1.0.0">
    <command name="jasypt/encrypt">
      <action class="io.fabric8.fabric.jaas.EncryptPasswordCommand" />
    </command>
  </command-bundle>

  <!-- AdminConfig property place holder for the org.apache.karaf.jaas -->
  <cm:property-placeholder persistent-id="io.fabric8.fabric.jaas"
               update-strategy="reload">
    <cm:default-properties>
      <cm:property name="encryption.name" value="" />
      <cm:property name="encryption.enabled" value="true" />
      <cm:property name="encryption.prefix" value="{CRYPT}" />
      <cm:property name="encryption.suffix" value="{CRYPT}" />
      <cm:property name="encryption.algorithm" value="MD5" />
      <cm:property name="encryption.encoding" value="hexadecimal" />
    </cm:default-properties>
  </cm:property-placeholder>

  <jaas:config name="karaf" rank="200">
    <jaas:module className="io.fabric8.jaas.ZookeeperLoginModule"
         flags="sufficient">
      path = /fabric/authentication/users
      encryption.name = ${encryption.name}
      encryption.enabled = ${encryption.enabled}
      encryption.prefix = ${encryption.prefix}
      encryption.suffix = ${encryption.suffix}
      encryption.algorithm = ${encryption.algorithm}
      encryption.encoding = ${encryption.encoding}
    </jaas:module>
    <jaas:module className="org.apache.karaf.jaas.modules.ldap.LDAPLoginModule"
                 flags="sufficient">
      initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
      connection.url=ldap://Hostname:Port
      connection.username=cn=Directory Manager
      connection.password=LDAPPassword
      connection.protocol=
      user.base.dn=ou=People,dc=localdomain
      user.filter=(&amp;(objectClass=inetOrgPerson)(uid=%u))
      user.search.subtree=true
      role.base.dn=ou=Groups,dc=localdomain
      role.name.attribute=cn
      role.filter=(uniquemember=%fqdn)
      role.search.subtree=true
      authentication=simple
    </jaas:module>
  </jaas:config>

  <!-- The Backing Engine Factory Service for the ZookeeperLoginModule -->
  <service interface="org.apache.karaf.jaas.modules.BackingEngineFactory">
    <bean class="io.fabric8.jaas.ZookeeperBackingEngineFactory" />
  </service>
</blueprint>
    You must customize the following settings in the ldap-module.xml file:
    connection.url
    Set this URL to the actual location of your directory server instance. Normally, this URL has the format, ldap://Hostname:Port. You must be sure to use a hostname that is accessible to all of the containers in the fabric (hence, you cannot use localhost as the hostname here). The default port for the 389 Directory Server is IP port 389.
    connection.username
    Specifies the username that is used to authenticate the connection to the directory server. For 389 Directory Server, the default is usually cn=Directory Manager.
    connection.password
    Specifies the password part of the credentials for connecting to the directory server.
    authentication
    You can specify either of the following alternatives for the authentication protocol:
    • simple implies that user credentials are supplied and you are obliged to set the connection.username and connection.password options in this case.
    • none implies that authentication is not performed. There is no need to set the connection.username and connection.password options in this case.
    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 200, it overrides all of the previously installed karaf realms (in the context of Fabric, you need to override the default ZookeeperLoginModule, which has a rank of 99).
    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.
    Important
    In a Fabric, the Zookeeper login module must be enabled, in addition to the LDAP login module. This is because Fabric uses the Zookeeper login module internally, to support authentication between ensemble servers. With the configuration shown here, Fabric tries to authenticate first of all against the Zookeeper login module and, if that step fails, it tries to authenticate against the LDAP login module.
  6. Save and close the ldap-module.xml resource by typing Ctrl-S and Ctrl-X.
  7. 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.
  8. 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.
  9. To check that the LDAP realm is activated, enter the following console command: 
    JBossFuse:karaf@root> jaas-realms
Index Realm                Module Class                                                                    
    1 karaf                org.apache.karaf.jaas.modules.ldap.LDAPLoginModule
    If the output of this command lists the ZookeperLoginModule, this means the LDAP realm is not yet activated. It might take a minute or so for activation of the LDAP realm to complete.

Test the LDAP authentication

Test the new LDAP realm by connecting to the running container using the 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 jdoe: 
    client -u jdoe -p secret
    You should successfully log into the container's remote console. At the command console, type jaas: followed by the [Tab] key (to activate content completion): 
    JBossFuse:jdoe@root> jaas:
jaas:cancel          jaas:groupadd        jaas:groupcreate     
jaas:groupdel        jaas:grouproleadd    jaas:grouproledel    
jaas:groups          jaas:manage          jaas:pending         
jaas:realms          jaas:roleadd         jaas:roledel         
jaas:update          jaas:useradd         jaas:userdel         
jaas:users
    You should see that jdoe has access to all of the jaas commands (which is consistent with the Administrator role).
  4. Log off the remote console by entering the logout command.
  5. Enter the following command to log on to the running container instance using the identity janedoe: 
    client -u janedoe -p secret
    You should successfully log into the container's remote console. At the command console, type jaas: followed by the [Tab] key (to activate content completion): 
    JBossFuse:janedoe@root> jaas:
jaas:cancel          jaas:groupadd        jaas:groupcreate     
jaas:groupdel        jaas:grouproleadd    jaas:grouproledel    
jaas:groups          jaas:manage          jaas:pending         
jaas:realms          jaas:roleadd         jaas:roledel         
jaas:useradd         jaas:userdel         jaas:users
    You should see that janedoe has access to almost all of the jaas commands, except for jaas:update (which is consistent with the Deployer role).
  6. Log off the remote console by entering the logout command.
  7. Enter the following command to log on to the running container instance using the identity crider: 
    client -u crider -p secret
    You should successfully log into the container's remote console. At the command console, type jaas: followed by the [Tab] key (to activate content completion): 
    JBossFuse:janedoe@root> jaas:
jaas:groupcreate    jaas:groups         jaas:realms
    You should see that crider has access to only three of the jaas commands (which is consistent with the Monitor role).
  8. Log off the remote console by entering the logout command.