Subscribe to WebSphere: eMailAlertsEmail Alerts newslettersWeekly Newsletters
Get WebSphere: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn

IBM WebSphere software products Authors: Pat Romanski, Liz McMillan, Yeshim Deniz, hyper filter, Timothée Bensimon

Related Topics: Java EE Journal, WebSphere

J2EE Journal: Article

Implementing WebSphere Security Through LDAP

Implementing WebSphere Security Through LDAP

The use of Lightweight Directory Authentication Protocol (LDAP) for WebSphere authentication and authorization offers the advantages of single sign-on across application servers and a vendor-neutral protocol and API.

Part 1 of this two-part series showed how to set up a directory and sample application infrastructure for demonstrating WebSphere authentication using LDAP. In Part 2 I take you through the process of setting up LDAP authentication for WebSphere through the following tasks:

  • Defining roles and constraints in the Web application deployment descriptor
  • Mapping roles to LDAP group entries in the enterprise application deployment descriptor
  • Configuring WebSphere to use an LDAP principal registry
  • Demonstrating the secured application features enabled by WebSphere and LDAP
  • Locking down the LDAP and browser transports using SSL (Secure Sockets Layer)

    Defining Web Application Roles and Constraints
    In this section I will show you how to define security roles and the constraints associated with them. Note that the roles and constraints will have no effect until security for the application server is enabled.

    Security Roles
    Carry out the following steps to create user and admin roles:
    1.   Open SecurityDemoWeb|WebDeployment Descriptor from the J2EE Navigator view.
    2.   Click the Security tab.
    3.   The top Security Roles tab should be selected. Press the Add button. A new role appears in the Security Roles box.
    4.   Edit the role in place to read "user".
    5.   Supply a description of End-user.
    6.   Add another role named admin.
    7.   Supply a description of Administrator.

    User Security Constraint
    Now we will relate Web resources to roles and transmission integrity. The following steps associate constraints with roles:
    1.   Click the Security Constraints tab on the deployment descriptor Security page.
    2.   Click the Add button to create a new security constraint. The constraint appears. In addition, a new Web resource collection appears in the right-hand group.
    3.   Press the Edit button for the Web resource collection. The Web Resource Collection dialog appears.
    4.   Name the collection user-collection.
    5.   All HTTP methods are constrained if you select none. Leave them unselected.
    6.   Press the Add button to add a URL pattern.
    7.   Change the pattern to "/*". This means all URLs in your document root are constrained by this constraint.
    8.   Press OK to update the Web resource collection.
    9.   Press the Edit button in the Authorized Roles group. The Define Authorization Constraint dialog appears. This is where you associate a role with a constraint.
    10.   Enter a description of the User constraint.
    11.   Select Role Name user (see Figure 1).
    12.   Press OK.

    Admin Security Constraint
    Carry out the following series of steps to create an administration security constraint:
    1.   In the Security Constraints group press the Add button.
    2.   Press the Edit button for the Web resource collection. The Web Resource Collection dialog appears.
    3.   Name the collection "admin-collection".
    4.   All HTTP methods will be constrained if you do not specify any of them. Leave all of them unselected.
    5.   Press the Add button to add a URL pattern.
    6.   This time, change the pattern to "/admin.jsp". This means that the given URL is constrained by this constraint. It is also constrained by the previous wildcard constraint. This means all administrators must also be users, but not the converse.
    7.   Press OK to update the Web resource collection.
    8.   Press the Edit button in the Authorized Roles group. The Define Authorization Constraint dialog appears.
    9.   Enter a description of the Administrator constraint.
    10.   Select Role Name admin (see Figure 2).
    13.   Press OK.

    Authentication Method
    Use the following steps to specify the authentication method for this application:
    1.   Select the Pages tab of the Web deployment descriptor.
    2.   In the Login group set the Authentication method dropdown to Basic. This means that the browser will pop up a login window when it receives an HTTP status of 401, meaning not authorized. WebSphere will receive the login credentials and try to authorize the user.
    3.   Save and close the Web deployment descriptor.

    Map Roles to LDAP Group Names
    So far the two security roles have no teeth in them. They need to be mapped to names in a user registry. WebSphere needs to map the role user to the LDAP users entry, and role admin to the LDAP admins entry. Carry out this mapping in the SecurityDemo enterprise application deployment descriptor with the following steps:
    1.   Open the SecurityDemo application deployment descriptor from the J2EE Navigator.
    2.   Press the Security tab.
    3.   Set WebSphere Bindings to Users/Groups.
    4.   Use the Add button in the Security group to add the role named user.
    5.   Use the Add button in the Groups group to add the LDAP group named users.
    6.   Use the Add button in the Security group to add the role named admin.
    7.   Use the Add button in the Groups group to add the LDAP group named admins.
    8.   Save and close the deployment descriptor.

    Application Server
    The easy way to configure the application server is to attempt to run the application on it. Afterward you can enable security on the new server configuration.

    Configure the Application Server
    WebSphere Studio includes a WebSphere V5.0 Test Environment server that is an actual WebSphere application server. Follow these steps to create a server configuration for WebSphere Studio:
    1.   In the J2EE Navigator view, rightclick project SecurityDemoWeb. Choose Run on Server. The Server Selection dialog appears.
    2.   Click the option to Set server as the project default (do not prompt). The dialog should resemble that shown in Figure 3.
    3.   Press OK to create the server and run the application. The start page should appear in the browser.

    WebSphere Security
    Notice that you were not asked for credentials and that you can access all three pages. This is because server security is enabled. Now you will need to enable security using the new LDAP user registry for authentication and role mapping.

    Administration Console
    The configuration page in WebSphere Studio does not expose the information needed to configure LTPA to use your LDAP user registry, so you need to use the WebSphere administration console. Follow these steps to configure LTPA:
    1.   Open the Server Perspective.
    2.   In the Server Configuration view, open the server configuration by right-clicking Servers|WebSphere V5.0 Test Environment and choosing Open.
    3.   Click the Configuration tab.
    4.   Set Enable administration console.
    5.   Clear Enable universal test client.
    6.   Save the configuration and close it.
    7.   In the Servers view, right-click the WebSphere V5.0 Test Environment. Choose Restart.
    8.   Wait for the console message. "Server server1 for eBusiness," signifying that restart is complete.
    9.   Open an external browser to http://localhost:9090/admin.
    10.   The console appears as shown in Figure 4. Note that there is no password field because security is not enabled.
    11.   Enter your last name as the User ID and press OK. The Administrative Console will open.

    Configure Settings for an LDAP User Registry
    Ensure that the IBM Directory Server 5.1 is running and then carry out the following steps:
    1.   Expand the Security|User Registries node in the left-hand pane.
    2.   In the Server User ID field, enter "was". Remember that this is the uid attribute value of the DN value cn=was,ou=people,o=rogers60, c=us in your LDAP directory.
    3.   In the Server User Password field, enter the value "secret". This is the userPassword attribute value for DN value cn=was,ou=people, o=rogers60,c=us. Note that this value is invisible to nonprivileged users of the directory.
    4.   From the Type dropdown list select IBM_Directory_Server.
    5.   Enter a host name of localhost or your remote host DNS name or IP address.
    6.   In the Base Distinguished Name (DN) field, enter your suffix, "o=rogers60,c=us".
    7.   In the Bind Distinguished Name (DN) field, enter "cn=root". This is the administration user ID for the LDAP directory that you defined previously.
    8.   In the Bind Password field, enter the value "secret".
    9.   Set the Ignore Case option.
    10.   Click the Apply button at the bottom.
    11.   A message invites you to press Save to apply the changes to the master configuration (see Figure 5).
    12.   Press Save on the tab bar or in the Messages pane. A confirmation message will appear.
    13.   Save to Master Configuration.

    Configure LTPA
    The WebSphere server will use LTPA for authentication. This is a forwardable security scheme that makes single sign-on (SSO) possible across applications running in participating Lotus Domino servers and WebSphere servers. Carry out the following steps:
    1.   Click the Security|LTPA tree node.
    2.   In the Password field enter the value "secret".
    3.   In the Confirm Password field enter the value "secret".
    4.   Press the tab labeled Generate Keys.
    5.   When the Message(s) box appears, press Save to apply changes.
    6.   Save to Master Configuration.

    Enable Global Security
    You have configured security settings. It is time to turn them on in the server. Use the following steps:
    1.   Click the Security|Global Security tree node.
    2.   Set the Enabled option.
    3.   The Enforce Java 2 Security option is set automatically. Leave it set.
    4.   Set the Active Security Mechanism dropdown to LTPA.
    5.   Set the Active User Registry drop down to LDAP.
    6.   Press Apply.
    7.   Press Save in the Message(s) box.
    8.   Save to Master Configuration.
    9.   Press Logout and then close the browser.
    10.   Return to the WebSphere Studio Servers view and restart the server.

    The Console view will show security initialized with LTPA and the host and port of your IBM Directory Server as the security principal.

    Run the Application
    You are ready to demonstrate LDAP-based authentication and authorization. Follow these steps:
    1.   In WebSphere Studio, open the Servers Perspective.
    2.   In the Servers view, right-click WebSphere V5.0 Test Environment, and choose Publish.
    3.   Right-click the server again and choose Restart. Wait for the console message: Server server1 open for e-business
    4.   Open an external browser to http://localhost:9080/SecurityDemoWeb. The browser security dialog appears because basic authentication was configured for the Web application.
    5.   Enter "lmauget" and "password" for the user ID and password (see Figure 6).
    6.   Press OK. The browser will render the start page (see Figure 7).
    7.   Notice that you have administrator access because of the LDAP group membership of the user ID lmauget. Click the Administer link to satisfy yourself that you have access to that page.
    8.   Close the browser. This destroys the session logon token, effectively logging you out.
    9.   Again start a browser on http://localhost:9080/SecurityDemoWeb. This time log in as "esuggins" with a password value of "password".
    10.   This time you receive normal access rights and do not see a link to the administration page (see Figure 8).

    The administration link is not visible, but can you access its page anyway? Try it. Enter http://localhost:9080/SecurityDemoWeb/admin.jsp as the browser address to try to access the page directly. You receive an access violation, as shown in Figure 9. Your production applications can prevent your users from seeing this ugly screen if you configure the deployment descriptor to show a more friendly error page for HTTP status 401.

    In addition, the WebSphere Studio Console view shows the following message:

    SECJ0129E: Authorization failed for esuggins
    while invoking GET on default_host:/SecurityDemoWeb/admin.jsp,
    Authorization failed, Not granted any of the required roles: admin

    This is helpful in debugging authorization problems because it shows the role that was not granted to the given user ID.

    Configure Secure Sockets Layer
    Congratulations! You have configured WebSphere to authenticate users via your LDAP user registry and authorize them to roles defined by LDAP mappings. There is still a data integrity and confidentiality exposure on the network. Passwords are happily flowing in clear text from the browser to WebSphere and from WebSphere to the LDAP directory. The cure is to enable Secure Sockets Layer (SSL) on both transports.

    Browser-to-Application SSL Transport
    Impose an SSL connection between the browser and any resource associated with the roles user and admin. Simply open the SecurityDemoWeb deployment descriptor to the Security tab. Then set the User Data Constraint to Confidential for the two constraints associated with those roles. Restart the server and access http://localhost: 9080/SecurityDemoWeb from a fresh instance of your external browser.

    The SSL certificate exchange causes a browser security alert because the server's dummy certificate name, jserver, probably does not match your site name (see Figure 10). For production, you would stop this alert by installing a certificate named for your site and signed by a trusted certification authority known to the browser.

    For this demonstration, press Yes to accept the server certificate and proceed to the login screen. Log in as one of your defined users.

    Notice that the URL protocol in the browser address field changes to an https protocol and the port becomes the https port 9443 defined in the test server. In addition, a lock icon appears on the status bar of the browser (see Figure 11).

    WebSphere-to-LDAP SSL Transport
    Now passwords and other data flowing between the browser and WebSphere are safe from snooping and undetected alteration, but protection during the transport between WebSphere and LDAP is lacking. Another SSL channel is needed.

    This task mainly consists of giving WebSphere a certificate so it can identify and trust the LDAP server. The unattended LDAP channel cannot present security alerts for manual intervention as the browser does. Configure a key file for your LDAP server, create a certificate in it, and then export that certificate to the WebSphere trusted certificate database.

    WebSphere Studio can display detailed instructions to follow for this procedure. Display them using the following steps:
    1.   Click the main menu Help item.
    2.   Search for: "Configuring SSL for LDAP".
    3.   Choose the result near the top, labeled "Configuring SSL for the LDAP client: WebSphere Application Server".

    Substitute real host names where relevant. The following high-level steps summarize the procedure:
    1.   Generate a key file for use by your LDAP server.
    2.   Generate a self-signed certificate within that key file (or request one from a certificate authority).
    3.   Export the certificate to a flat file.
    4.   Import the certificate flat file to the trust file on WebSphere.

    After configuring the certificates, use the following steps to enable SSL in the server:
    1.   Ensure that WebSphere is running.
    2.   Invoke http://localhost:9080/admin from a browser to open the WebSphere Administration Console. Login as was/password, as defined in your LDAP server.
    3.   Expand the tree to node Security|User Registries|LDAP.
    4.   Alter field Port to 636.
    5.   Set option SSL Enabled.
    6.   Log out.
    7.   In WebSphere Studio, use the Server view to restart the server.

    Use a browser to access the application. The application should operate as before, except that the back-end transport channel between WebSphere and the LDAP server is secure.

    This two-part series demonstrated how to create a WebSphere application that is secured through LDAP and SSL. J2EE applications can assign roles to constraints used to secure resources by the URL or HTTP method. A secured J2EE server, such as WebSphere, maps those roles to principals in some registry. WebSphere LTPA can be configured to use an LDAP server as its principal registry. Advantages include centralized user management, the capability to use the LDAP directory for centralized organizational data, and the capability to enable single sign-on for applications across a set of servers. The directory server controls selective access to LDAP entries such as passwords. WebSphere, the directory server, and the client browser can all use SSL transport to secure data on the transport layer.


  • Nilsson, D., and Mauget, L. (2003). Building J2EE Applications with WebSphere. John Wiley & Sons.
  • High, R., Rochat, K., and Knutson, J. (2003). Professional IBM WebSphere 5.0 Application Server. Wrox Press Inc.
  • Barlen, T., et al. (2002). Implementation and Practical Use of LDAP on the IBM iSeries Server. IBM Redbooks.
  • Howes, T, et al. (1998). Understanding and Deploying LDAP Directory Services. New Riders Publishing.
  • Howes, T, and Smith, M. (1997). LDAP: Programming Directory-Enabled Applications With Lightweight Directory Access Protocol. Que.
  • More Stories By Louis Mauget

    Lou Mauget is a senior consultant with CrossLogic Corporation where his assignments include J2EE mentoring and designing instructional material. He has coauthored three computer-related books. His prior career at IBM included work as a consultant, programmer, and developer.

    Comments (1) View Comments

    Share your thoughts on this story.

    Add your comment
    You must be signed in to add a comment. Sign-in | Register

    In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.

    Most Recent Comments
    Octavio Dure 07/01/03 03:29:00 PM EDT

    Great Article !!!
    I' d now like to improve this a litt