User Guide Integrating LDAP with Payara® Server The Payara® Platform - Production-Ready, Cloud Native and Aggressively Compatible. Integrating LDAP with Payara® Server Contents Starting the LDAP Server 1 Configuring Security 5 Creating a Web Application 6 Extracting User Information 11 Seamless Authentication and Authorization 17 About Payara Services, Ltd 18 Integrating LDAP with Payara® Server If you work in an organization with a robust IT department, it’s very likely that you are using a LDAP server to handle your user directory information. You probably have to follow some general guidelines dictating that all web applications deployed within the organization’s infrastructure must access this user directory; and must authenticate and authorize the users that will interact with them. This is a very common scenario nowadays. In this guide, I will illustrate the implementation of the LDAP integration using a sample scenario: integrate Payara® Server with a LDAP user directory and manage the authentication and authorization of a sample web application. Starting the LDAP Server There are many different LDAP server implementations in the market today (in both commercial and open source models). For our scenario, we will quickly start an OpenDJ instance using a Docker container and set up a directory domain with some test users and groups. First, we start with a new Docker image that will download the OpenDJ binaries and run them in a container. This is a Java based image, since OpenDJ needs the JDK to run: FROM java:8 MAINTAINER Fabio Turizo <[email protected]> WORKDIR /opt ENV JAVA_HOME /usr/lib/jvm/java-8-openjdk-amd64/ ENV MVN_REPO=https://maven.forgerock.org/repo/repo/org/forgerock/opendj ENV OPENDJ_VERSION=3.0.0 ENV SERVER_PATH opendj-server-legacy RUN curl $MVN_REPO/$SERVER_PATH/$OPENDJ_VERSION/$SERVER_PATH $OPENDJ_VERSION. zip \ -o /tmp/opendj.zip && \ unzip /tmp/opendj.zip -d /opt && \ rm /tmp/opendj.zip ADD run.sh /opt/opendj/run.sh ADD users.ldif /opt/opendj/initial.ldif EXPOSE 1389 4444 WORKDIR /opt/opendj CMD ["./run.sh"] 1 Integrating LDAP with Payara® Server You will notice that we are using 2 external files in this image:run.sh and users.ldif. Let’s start with the users.ldif file, which we are using to create a starting set of users and groups: dn: dc=payara,dc=fish objectClass: top objectClass: domain dc: payara dn: cn=Alfa Michael,dc=payara,dc=fish objectClass: organizationalPerson objectClass: top objectClass: person objectClass: inetOrgPerson uid: malfa mail: [email protected] givenName: Michael sn: Alfa cn: Alfa Michael userPassword: {SSHA}nirDyc9/XKLXqUqlR3sqD1De3qhybUqZQeU8pg== creatorsName: cn=Directory Manager,cn=Root DNs,cn=config dn: cn=Beta Carol,dc=payara,dc=fish objectClass: organizationalPerson objectClass: top objectClass: person objectClass: inetOrgPerson uid: cbeta mail: [email protected] givenName: Carol sn: Beta cn: Beta Carol userPassword: {SSHA}ALhq+r+G3znVsPH70FkzyhHRZiN092w1GXiAZw== dn: cn=Omega John,dc=payara,dc=fish objectClass: organizationalPerson objectClass: top objectClass: person objectClass: inetOrgPerson uid: jomega mail: [email protected] givenName: John 2 Integrating LDAP with Payara® Server sn: Omega cn: Omega John userPassword: {SSHA}KVj0XDak6E+IRecFkkCveTzsmW014IlGN2LlWg== dn: cn=Admins,dc=payara,dc=fish objectClass: groupOfNames objectClass: top member: cn=Alfa Michael,dc=payara,dc=fish description: Administrators cn: Admins entryUUID: b7f3af29-3834-4765-9978-33e419073a65 createTimestamp: 20161019012425Z creatorsName: cn=Directory Manager,cn=Root DNs,cn=config dn: cn=Common,dc=payara,dc=fish objectClass: groupOfNames objectClass: top member: cn=Beta Carol,dc=payara,dc=fish member: cn=Omega John,dc=payara,dc=fish description: Common Users cn: Common entryUUID: 8bc4ac5c-3313-4f9d-a111-6c933191fb2d createTimestamp: 20161019012453Z creatorsName: cn=Directory Manager,cn=Root DNs,cn=config The contents of this file will allow us to create an initial set of 3 users (Michal Alfa, Carol Beta and John Omega) and 2 groups (Admin and Common). These objects are under the dc=payara, dc=fish base domain name. Finally, we have the run.sh file. This file handles the OpenDJ installation and initialization using bash scripting: #!/usr/bin/env bash cd /opt/opendj/ if [ ! -d ./data/config ] ; then echo "Executing OpenDJ first setup" MANAGER_USER=${MANAGER:-"cn=Directory Manager"} BASE_DN=${BASE_DN:-"dc=payara,dc=fish"} PASSWORD=${PW:-admin} 3 Integrating LDAP with Payara® Server ./setup --cli --hostname localhost --ldapPort 1389 --rootUserDN "${MANAGER_ USER}" \ --rootUserPassword "${PASSWORD}" --backendType pdb --baseDN "${BASE_DN}" \ --ldifFile "/opt/opendj/initial.ldif" --acceptLicense --no-prompt \ --noPropertiesFile else echo "Starting OpenDJ" ./bin/start-ds fi if (bin/status -n -w "${PASSWORD}" | grep Started); then echo "OpenDJ is running" while true; do sleep 100000; done fi This bash script will detect if there’s a previous OpenDJ installation (by checking out if the local data directory ./data/config exists). If not, it will setup OpenDJ using the command line interface option of the setup binary utility. The script provides the values for the installation options (root user, root password, LDAP port, etc.), but some of them can be changed with environment variables (${MANAGER}, ${PASSWORD}, etc.). If OpenDJ is already installed, then the script will simply start the server. Finally, we let the script run the container indefinitely by starting an infinite loop that sleeps the input at frequent intervals. Now, we proceed to build this image: docker build -t fturizo/opendj . And then start a new container with it: docker run -d -p 1389:1389 -v ~/opendj-data:/opt/opendj/data –-name=opendj fturizo/opendj 4 Integrating LDAP with Payara® Server You can now connect to this LDAP server using port 1389. Using an LDAP Browser tool, we can check that our schema was imported correctly and the OpenDJ server is running: Configuring Security After starting the LDAP Server - now we need to configure a new LDAP security realm in our Payara Server instance for our Java EE application to connect to the user directory through the JAAS (Java Authentication and Authorization Services) API. With a Payara Server domain running, we execute the following command: create-auth-realm --classname=com.sun.enterprise.security.auth.realm.ldap. LDAPRealm \ --property=jaas-context=ldapRealm:\ base-dn="dc=payara, dc=fish":\ directory="ldap://192.168.99.100:1389" \ group-search-filter="member=%d" \ --target=server-config userDirectoryRealm 5 Integrating LDAP with Payara® Server With this command, we’re creating a new LDAP security realm called userDirectoryRealm that will authenticate and authorize both users and groups for our Java EE web application. You will notice that we are setting the following properties: • Base DN: We set this property to the base directory name of our LDAP, in this case dc=payara, dc=fish. • Directory: This property points to the location of our LDAP server. Pay attention to the port that we are using (1389). • Group Search Filter: With this property, we’re overriding the default search filter query that the realm uses to identify which users are part of a group. Since OpenDJ uses the object attribute member, we’re setting the query to use it instead of the default configured attrib- ute (uniquemember). What happens if you want to fine tune the directory searches and filters specifically for your organ- ization? You can use the following additional properties: • group-base-dn: set this property to the base directory name - the realm will use it to read the group data. For example: cn=Organization Groups would imply that all the organi- zation’s groups live in this directory object. • search-bind-dn: set this property to the directory name of an administrator user the realm can bind to in case your LDAP server doesn’t allow anonymous binding (in our case, the default setting of OpenDJ is to indeed allow anonymous binding). • search-bind-password: the password of the DN set in the search-bind-dn property • search-filter: you can use this property to customize the search query used to locate a user in the directory tree. For example: ou=People, uid=%s would limit the search to all users under the People organization unit object. Creating a Web Application Next, we proceed to create a sample web application to test out our LDAP configuration. For this application, we will create 3 sample JSF pages: 1 - Our first page will be anindex.xhtml landing page that will simply print out the UID/Username of the authenticated user: <?xml version='1.0' encoding='UTF-8' ?> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://xmlns.jcp.org/jsf/html"> <h:head> <title>LDAP Test</title> </h:head> <h:body> 6 Integrating LDAP with Payara® Server Welcome #{welcomeBean.user}! <h:form> <h:commandLink value="Go to admins page" action="admin/index. xhtml?faces-redirect=true"/> <br/> <h:commandLink value="Go to commons page" action="common/index. xhtml?faces-redirect=true"/> </h:form> </h:body> </html> Notice that we are using a bean of name WelcomeBean to get the username (more on this bean later). We also are setting some navigation links to access the other two pages. 2 - Another page, admin/index.xhtml (under folder admin), that only users that belong to the Admins group can access: <?xml version='1.0' encoding='UTF-8' ?> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://xmlns.jcp.org/jsf/html"> <h:head> <title>For Admins Only</title> </h:head> <h:body> Welcome #{welcomeBean.user}! Since you are an administrator, you can access this page </h:body> </html> 3 - A finalcommon/index.xhtml page (under folder common) that both common users and admin- istrators can access: <?xml version='1.0' encoding='UTF-8' ?> <!DOCTYPE html> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:h="http://xmlns.jcp.org/jsf/html"> <h:head> <title>For Everyone Actually</title> </h:head> 7 Integrating LDAP with Payara® Server <h:body> Welcome #{welcomeBean.user}! You are in the common group, so you can see this page.