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 Goals 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 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 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 OSy7) on the fedoraproject.org site. Install 389 Directory Server 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: 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): 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. After installing the 389 directory server packages, enter the following command to configure the directory server: 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. For more details about how to install 389 Directory Server , see the Download page. Install 389 Management Console 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): On Windows platforms -see the Windows Console download instructions from fedoraproject.org . Connect the console to the server To connect the 389 Directory Server Console to the LDAP server: Enter the following command to start up the 389 Management Console: 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). The 389 Management Console window appears. Select the Servers and Applications tab. In the left-hand pane, drill down to the Directory Server icon. Select the Directory Server icon in the left-hand pane and click Open , to open the 389 Directory Server Console . In the 389 Directory Server Console , click the Directory tab, to view the Directory Information Tree (DIT). Expand the root node, YourDomain (usually named after a hostname, and shown as localdomain in the following screenshot), to view the DIT. 8.3. Add User Entries to the Directory Server 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 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 In this portion of the tutorial you will Add three user entries to the LDAP server Add four groups to the LDAP server Adding user entries Perform the following steps to add user entries to the directory server: Ensure that the LDAP server and console are running. See Section 8.2, "Set-up a Directory Server and Console" . 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). Right-click the People node, and select menu:[ > New > > User > ] from the context menu, to open the Create New User dialog. Select the User tab in the left-hand pane of the Create New User dialog. Fill in the fields of the User tab, as follows: Set the First Name field to John . Set the Last Name field to Doe . Set the User ID field to jdoe . Enter the password, secret , in the Password field. Enter the password, secret , in the Confirm Password field. Click OK . 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. 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 To add the groups that define the roles: In the Directory tab of the Directory Server Console , drill down to the Groups node, under the YourDomain node. Right-click the Groups node, and select menu:[ > New > > Group > ] from the context menu, to open the Create New Group dialog. Select the General tab in the left-hand pane of the Create New Group dialog. Fill in the fields of the General tab, as follows: Set the Group Name field to admin . Optionally, enter a description in the Description field. Select the Members tab in the left-hand pane of the Create New Group dialog. Click Add to open the Search users and groups dialog. In the Search field, select Users from the drop-down menu, and click the Search button. From the list of users that is now displayed, select John Doe . Click OK , to close the Search users and groups dialog. Click OK , to close the Create New Group dialog. 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 . 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 . 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 . 8.4. Enable LDAP Authentication in the OSGi Container 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: LDAPLoginModule options -are described in detail in Section 2.1.7, "JAAS LDAP Login Module" . Configurations for other directory servers -this tutorial covers only 389-DS . For details of how to configure other directory servers, such as Microsoft Active Directory, see the section called "Filter settings for different directory servers" . Procedure for standalone OSGi container To enable LDAP authentication in a standalone OSGi container: Ensure that the X.500 directory server is running. Start the Karaf container by entering the following command in a terminal window: Create a 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="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> 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. 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 Test the new LDAP realm by connecting to the running container using the Karaf client utility, as follows: Open a new command prompt. Change directory to the Karaf InstallDir /bin directory. Enter the following command to log on to the running container instance using the identity jdoe : 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): You should see that jdoe has access to all of the jaas commands (consistent with the admin role). Log off the remote console by entering the logout command. Enter the following command to log on to the running container instance using the identity janedoe : 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): You should see that janedoe has access to almost all of the jaas commands (consistent with the manager role). Log off the remote console by entering the logout command. Enter the following command to log on to the running container instance using the identity crider : 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): You should see that crider has access to only five of the jaas commands (consistent with the viewer role). Log off the remote console by entering the logout command. Troubleshooting 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: From the Karaf console, enter the following command to increase the logging level to DEBUG : Observe the Karaf log in real time: To escape from the log listing, type Ctrl-C.

Commands:
sudo dnf install 389-ds
sudo setup-ds-admin.pl
sudo dnf install 389-console
389-console
./bin/fuse
<?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>
./client -u jdoe -p secret
jdoe@root()> jaas: Display all 31 possibilities? (31 lines)? jaas:cancel jaas:group-add jaas:whoami
./client -u janedoe -p secret
janedoe@root()> jaas: Display all 25 possibilities? (25 lines)? jaas:cancel jaas:group-add jaas:users
./client -u crider -p secret
crider@root()> jaas: jaas:manage jaas:realm-list jaas:realm-manage jaas:realms jaas:user-list jaas:users
log:set DEBUG
log:tail