Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 8. LDAP Authentication Tutorial

Abstract

This tutorial explains how to set up an X.500 directory server and configure the OSGi container to use LDAP authentication.

8.1. Tutorial Overview
Copy link

Goals
Copy link

In this tutorial you will:

  • Install 389 Directory Server
  • Add user entries to the LDAP server
  • Add groups to manage security roles
  • Configure Fuse to use LDAP authentication
  • Configure Fuse to use roles for authorization
  • Configure SSL/TLS connections to the LDAP server

8.2. Set-up a Directory Server and Console
Copy link

This stage of the tutorial explains how to install the X.500 directory server and the management console from the Fedora 389 Directory Server project. If you already have access to a 389 Directory Server instance, you can skip the instructions for installing the 389 Directory Server and install the 389 Management Console instead.

Prerequisites
Copy link

If you are installing on a Red Hat Enterprise Linux platform, you must first install the Extra Packages for Enterprise Linux (EPEL). See the installation notes under RHEL/Cent OS/ EPEL ( RHEL 6, RHEL 7, Cent OS 6, Cent OSý7) on the fedoraproject.org site.

Install 389 Directory Server
Copy link

If you do not have access to an existing 389 Directory Server instance, you can install 389 Directory Server on your local machine, as follows:

  1. On Red Hat Enterprise Linux and Fedora platforms, use the standard dnf package management utility to install 389 Directory Server. Enter the following command at a command prompt (you must have administrator privileges on your machine): 

    sudo dnf install 389-ds
    Copy to Clipboard Toggle word wrap
    Note

    The required 389-ds and 389-console RPM packages are available for Fedora, RHEL6+EPEL, and CentOS7+EPEL platforms. At the time of writing, the 389-console package is not yet available for RHEL 7.

  2. After installing the 389 directory server packages, enter the following command to configure the directory server: 

    sudo setup-ds-admin.pl
    Copy to Clipboard Toggle word wrap

    The script is interactive and prompts you to provide the basic configuration settings for the 389 directory server. When the script is complete, it automatically launches the 389 directory server in the background.

  3. For more details about how to install 389 Directory Server, see the Download page.

Install 389 Management Console
Copy link

If you already have access to a 389 Directory Server instance, you only need to install the 389 Management Console, which enables you to log in and manage the server remotely. You can install the 389 Management Console, as follows:

  • On Red Hat Enterprise Linux and Fedora platforms—use the standard dnf package management utility to install the 389 Management Console. Enter the following command at a command prompt (you must have administrator privileges on your machine): 

    sudo dnf install 389-console
    Copy to Clipboard Toggle word wrap
  • On Windows platforms—see the Windows Console download instructions from fedoraproject.org.

Connect the console to the server
Copy link

To connect the 389 Directory Server Console to the LDAP server:

  1. Enter the following command to start up the 389 Management Console: 

    389-console
    Copy to Clipboard Toggle word wrap

  2. A login dialog appears. Fill in the LDAP login credentials in the User ID and Password fields, and customize the hostname in the Administration URL field to connect to your 389 management server instance (port 9830 is the default port for the 389 management server instance).

    LDAP Console Login
    View larger image
    LDAP Console Login
  3. The 389 Management Console window appears. Select the Servers and Applications tab.

  4. In the left-hand pane, drill down to the Directory Server icon.

    LDAP Console Open
    View larger image
    LDAP Console Open
  5. Select the Directory Server icon in the left-hand pane and click Open, to open the 389 Directory Server Console.
  6. In the 389 Directory Server Console, click the Directory tab, to view the Directory Information Tree (DIT).

  7. Expand the root node, YourDomain (usually named after a hostname, and shown as localdomain in the following screenshot), to view the DIT.

    LDAP ServerConsole DIT
    View larger image
    LDAP ServerConsole DIT

8.3. Add User Entries to the Directory Server
Copy link

The basic prerequisite for using LDAP authentication with the OSGi container is to have an X.500 directory server running and configured with a collection of user entries. For many use cases, you will also want to configure a number of groups to manage user roles.

Alternative to adding user entries
Copy link

If you already have user entries and groups defined in your LDAP server, you might prefer to map the existing LDAP groups to JAAS roles using the roles.mapping property in the LDAPLoginModule configuration, instead of creating new entries. For details, see Section 2.1.7, “JAAS LDAP Login Module”.

Goals
Copy link

In this portion of the tutorial you will

Adding user entries
Copy link

Perform the following steps to add user entries to the directory server:

  1. Ensure that the LDAP server and console are running. See Section 8.2, “Set-up a Directory Server and Console”.

  2. In the Directory Server Console, click on the Directory tab, and drill down to the People node, under the YourDomain node (where YourDomain is shown as localdomain in the following screenshots).

    directory information tree in the LDAP browser
    View larger image
    directory information tree in the LDAP browser
  3. Right-click the People node, and select menu:[ > New > > User > ] from the context menu, to open the Create New User dialog.
  4. Select the User tab in the left-hand pane of the Create New User dialog.

  5. Fill in the fields of the User tab, as follows:

    1. Set the First Name field to John.
    2. Set the Last Name field to Doe.
    3. Set the User ID field to jdoe.
    4. Enter the password, secret, in the Password field.

    5. Enter the password, secret, in the Confirm Password field.

      Filling the fields of the User tab in the Create New User dialog
      View larger image
      Filling the fields of the User tab in the Create New User dialog
  6. Click OK.

  7. Add a user Jane Doe by following Step 3 to Step 6.

    In Step 5.e, use janedoe for the new user’s User ID and use the password, secret, for the password fields.

  8. Add a user Camel Rider by following Step 3 to Step 6.

    In Step 5.e, use crider for the new user’s User ID and use the password, secret, for the password fields.

Adding groups for the roles
Copy link

To add the groups that define the roles:

  1. In the Directory tab of the Directory Server Console, drill down to the Groups node, under the YourDomain node.
  2. Right-click the Groups node, and select menu:[ > New > > Group > ] from the context menu, to open the Create New Group dialog.
  3. Select the General tab in the left-hand pane of the Create New Group dialog.

  4. Fill in the fields of the General tab, as follows:

    1. Set the Group Name field to admin.

    2. Optionally, enter a description in the Description field.

      Filling the fields of the General tab in the Create New Group dialog
      View larger image
      Filling the fields of the General tab in the Create New Group dialog

  5. Select the Members tab in the left-hand pane of the Create New Group dialog.

    Filling the fields of the Members tab in the Create New Group dialog
    View larger image
    Filling the fields of the Members tab in the Create New Group dialog
  6. Click Add to open the Search users and groups dialog.

  7. In the Search field, select Users from the drop-down menu, and click the Search button.

    LDAP SearchUsers
    View larger image
    LDAP SearchUsers
  8. From the list of users that is now displayed, select John Doe.
  9. Click OK, to close the Search users and groups dialog.
  10. Click OK, to close the Create New Group dialog.

  11. Add a manager role by following Step 2 to Step 10.

    In Step 4, enter manager in the Group Name field.

    In Step 8, select Jane Doe.

  12. Add a viewer role by following Step 2 to Step 10.

    In Step 4, enter viewer in the Group Name field.

    In Step 8, select Camel Rider.

  13. Add an ssh role by following Step 2 to Step 10.

    In Step 4, enter ssh in the Group Name field.

    In Step 8, select all of the users, John Doe, Jane Doe, and Camel Rider.

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
Copy link

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

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 the Karaf container by entering the following command in a terminal window: 

    ./bin/fuse
    Copy to Clipboard Toggle word wrap
  3. Create a 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="2.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://localhost:389
      connection.username=cn=Directory Manager
      connection.password=DIRECTORY_MANAGER_PASSWORD
      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>
    Copy to Clipboard Toggle word wrap

    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. You must not 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 Fuse. 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 details about how to configure Fuse 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 Karaf container’s deploy/ directory (hot deploy).

    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.

Test the LDAP authentication
Copy link

Test the new LDAP realm by connecting to the running container using the Karaf client utility, as follows:

  1. Open a new command prompt.
  2. Change directory to the Karaf 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
    Copy to Clipboard Toggle word wrap

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

    jdoe@root()> jaas:
Display all 31 possibilities? (31 lines)?
jaas:cancel
jaas:group-add
...
jaas:whoami
    Copy to Clipboard Toggle word wrap

    You should see that jdoe has access to all of the jaas commands (consistent with the admin 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
    Copy to Clipboard Toggle word wrap

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

    janedoe@root()> jaas:
Display all 25 possibilities? (25 lines)?
jaas:cancel
jaas:group-add
...
jaas:users
    Copy to Clipboard Toggle word wrap

    You should see that janedoe has access to almost all of the jaas commands (consistent with the manager 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
    Copy to Clipboard Toggle word wrap

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

    crider@root()> jaas:
jaas:manage
jaas:realm-list
jaas:realm-manage
jaas:realms
jaas:user-list
jaas:users
    Copy to Clipboard Toggle word wrap

    You should see that crider has access to only five of the jaas commands (consistent with the viewer role).

  8. Log off the remote console by entering the logout command.

Troubleshooting
Copy link

If you run into any difficulties while testing the LDAP connection, increase the logging level to DEBUG to get a detailed trace of what is happening on the connection to the LDAP server.

Perform the following steps:

  1. From the Karaf console, enter the following command to increase the logging level to DEBUG: 

    log:set DEBUG
    Copy to Clipboard Toggle word wrap

  2. Observe the Karaf log in real time: 

    log:tail
    Copy to Clipboard Toggle word wrap

    To escape from the log listing, type Ctrl-C.

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