Introduction

To accommodate certain business requirements, it is often necessary to modify the default Lightweight Directory Access Protocol (hereafter called LDAP) schema that IBM^TM WebSphere^TM Portal (hereafter called WebSphere Portal) uses. For example, you may need to add attributes to the LDAP schema, such as an account number or health insurance number. Or, you may already have custom object classes in LDAP. You can configure WebSphere Portal to use a custom object class in LDAP.

This article tells how to create and configure a custom object class in LDAP. It takes you through creating an object class and adding it to the LDAP schema, and creating a file to load data into LDAP. Then it describes how to configure WebSphere Portal Server to authenticate and authorize users of the custom class.

Specifically, it describes:

• When you should consider modifying the custom LDAP schema
• How to modify the default LDAP schema
• How to create a new schema
• Configuring WebSphere Portal Server to use a custom LDAP schema

To get the most out of this article, you should have a general understanding of Lightweight Directory Access Protocol (LDAP) based authentication and authorization mechanisms commonly employed in J2EE application servers. This article deals specifically with the LDAP based security in WebSphere Application Server. You do not need to have a detailed understanding of LDAP schema and object classes.

Prerequisites

The sample scenario has been tested with WebSphere Portal V4 and with the LDAP suffix as dc= xyz ,dc= com .

To be able to run the samples, you need to make sure that:

1. IBM Directory Server Version 3.2.2 or Version 4.1, or another LDAP Server that supports LDAP Data Interchange Format(hereafter called LDIF), is installed.
   The example scenario described here was tested with IBM Directory Server V 3.2.2 and V 4.1.
2. IBM Directory Server is configured with a Web server.
   In this article, IBM Directory Server is configured with IBM HTTP Server Version 1.3.19. You should be able to bring up the IBM Directory Web Administration Console at http://hostname/ldap. You can login to the Web Administration Console with the administrator username (assumed here as cn= admin ) and password (assumed here as ldap).
3. WebSphere Portal Version 4.1.x or Version 4.2 is installed on WebSphere Application Server Advanced Edition Version 4.0.2, or WebSphere Application Server V4.0.4 with WebSphere Portal Version 4.2).
   This WebSphere Portal installation must be a typical installation with an LDAP Server using the suffix : dc=xyz,dc=com. It cannot be a development installation.
4. IBM Directory Version 3.2.2, or another LDAP that supports LDIF format (such as Netscape LDAP), is configured with WebSphere Portal. Alternatively, you can use IBM Directory v4.1 for WebSphere Portal Version 4.2.
5. WebSphere Portal is configured with the default LDAP schema.
6. WebSphere Security is set up with the defaults; that is, no changes have been made to the WebSphere Application Server Security after installing WebSphere Portal.

For help installing WebSphere Portal, see WebSphere Portal Server V4.1 AIX 5L Installation or WebSphere Portal Server V4.1 Windows 2000 Installation.

You should be able to do the following on your WebSphere Portal Server installation.

1. Bring up the following URL:
   http:///wps/myportal and log in with username = wpsadmin.
   This article assumes password = wpsadmin, but you can use your own password.)
2. Bring up the IBM Directory Web Administration Console http://hostname/ldap and login with the LDAP Administrator user name (assumed here as cn = admin) and password (assumed here as ldap).

LDAP terminology

This article uses the following terms:

• directory entry: A directory entry describes some object such as a person or a department. Each entry contains one or more attributes that describe the entry. Each attribute has a type and value.
• Distinguished Name (DN): Each directory entry has a name called a distinguished name (DN) that uniquely identifies it. Example: DN uid=wpsadmin,cn=users, dc=xyz, dc=com represents a directory entry for a person with uid=wpsadmin.
• suffix: The highest entry stored by a server is called a suffix. Example: in DN uid=wpsadmin,cn=users, dc=xyz, dc=com the suffix is: dc=xyz, dc=com.
• Directory Information Tree (DIT): The directory entries can be arranged into a hierarchical tree-like structure based on their distinguished names (DN). This tree of directory entries is called the Directory Information Tree (DIT).
• schema: The object classes that a directory server can store and the attributes they contain are described by schema. Schema define which object classes are allowed where in the directory, which attributes they must contain, which attributes are optional, and the syntax of each attribute. A schema is the collection of attribute type definitions, object class definitions, and other information. A server uses a schema to determine how to match a filter or attribute value assertion (in a compare operation) against the attributes of an entry, and whether to permit add and modify operations.

LDAP object classes used in this article

The default LDAP schema used by WebSphere Portal is defined as part of the Request for Comments (RFC) 2251. The object classes used in this article are shown in Table 1. See the Appendix.doc in the ldapexamples.zip download file for a complete list of the attributes.

Table 1. Object classes used in this article

Back to top

When should you modify LDAP schema?

Creating a directory design that has the flexibility to accommodate changes within the organization is probably the single most important task in implementing the directory service. Data stored in LDAP should:

1. Typically be read much more often than it is written; that is, it should be read-intensive data. The LDAP database is optimized for read operations (for example, LDAP searches).
2. Be accessed from more than one system or client.
3. Not be large, unstructured objects.

Modifying the default object class or any default attribute in LDAP is not recommended because existing applications may be using it. If the definition of one of the default attributes, such as givenName, needs to be changed, then you should define a new attribute.

For example, suppose you need to add an attribute called account number in the class inetOrgPerson. In this scenario you need to create a new object class; for example, called portalUser. The portalUser object class would have the same attributes as the inetOrgPerson object class and could add other attributes such as account number. Adding a new class prevents potential conflicts when a new version of the directory is installed and the default schema is refreshed.

Important: One special object class, called top, has no superiors. The top object class includes the mandatory objectClass attribute. Therefore the attributes in top appear in all directory entries.

The default LDAP schema installed by the WebSphere Portal Server installation uses the object class inetOrgPerson. This is sufficient for most organizations because it was defined to meet the requirements found in today's Internet and Intranet directory service deployments. However, in some cases it may not be sufficient, as shown by the following example.

Suppose you need to add the employee's account number, insurance id, and role. These attributes do not exist in inetOrgPerson. You can subclass inetOrgPerson to suit your specific need. These data are read intensive and are typically needed by many systems in an organization; therefore, they are good candidates for storing in LDAP. In this case, you would add a new object class, which is a subclass of inetOrgPerson. The new object class would include the additional attributes for employee's account number, insurance_id, and role.

Back to top

Scenario: Creating a custom object class

In this section, you see a specific scenario that illustrates when and how you might create an object class in LDAP.

A mythical company called XYZ Technologies wants to implement LDAP as the central repository for profile information. This profile information will be used by several business applications, including WebSphere Portal. The attributes to be stored are the first name, last name, insurance id, and account number and roles of every entry (also called user) in LDAP. The default object class used by WebSphere Portal is inetOrgPerson. This has the attributes first name (called Common name), and last name, but does not have these attributes: insurance_id and account number . Therefore, XYZ Technologies creates a new object class calledl portalUser, that is a subclass of inetOrgPerson. The portalUser object class has all the attributes of inetOrgPerson and the additonal attributes insurance_id and account number.

XYZ Technologies will use the directory tree structure shown in Figure 1. The suffix of the directory used by WebSphere Portal is dc=xyz, dc=com. The LDAP Directory Information Tree (DIT) is organized into a hierarchy of organizational units, or ou's, which are containers for Portal users and groups. The top of the hierarchy is: cn=Users and ou=groups. The ou=groups has another sub tree called ou=PortalGroups. XYZ Technologies can configure WebSphere Portal Server to use the ou=PortalGroups subtree as its base for groups. The ou=PortalGroups subtree has the following groups: HumanResources, Accounts, BaseballTeam.

Table 2. Directory schema: Description of the portalUser object class. This class inherits inetOrgPerson

Configuring IBM Directory Server with the new object class

The IBM Directory Server maintains its schema files in the /usr/ldap/etc directory. When you add new attributes and object classes to the directory schema, you record them in the V3.modifiedschema file. A new LDAP server can be configured to have the same schema by copying V3.modifiedschema to its /usr/ldap/etc directory in Unix or AIX or to the <ldap_install_directory>\etc directory in Win2K.

The portalUser object class inherits from inetOrgPerson object class, as indicated by the SUP keyword. It has these optional attributes (indicated by the MAY keyword ):

• portalUserRole, which is a multi-valued attribute
• insuranceId
• accountNumber

Either copy the code below and paste it into <ldap_install_directory > /etc/V3.modifiedschema file, or use the V3.modifiedschema in the ldapexamples.zip download file.

Listing 1. V3.modifiedschema

objectClasses { ( portalUser-OID NAME
'portalUser' DESC 'Custom Portal User' SUP
inetOrgPerson MAY ( portalUserRole $ accountNumber $
insuranceId ) ) }

attributeTypes { ( portalUserRole-OID NAME
'portalUserRole' DESC 'Flag indicating the membership'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) (
accountNumber-OID NAME 'accountNumber' DESC 'Policy or
Account Numbers ' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
) ( insuranceId-OID NAME 'insuranceId' DESC 'Insurance
Id' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) }

IBMattributeTypes { ( portalUserRole-OID ) (
accountNumber-OID EQUALITY ) ( insuranceId-OID) }

You would add this schema definition for the portalUser object class. This file has the object class definition for portalUser. You specify the SUP keyword for portalUser to indicate that it inherits from inetOrgPerson. The class portalUser has the following optional attributes:

portalUserRole AccountNumber InsuranceID

The keyword MAY indicates optional attributes; the MUST keyword indates mandatory attributes.

These attribute definitions are also listed in the schema definition. The Object Identifier (OID: 1.3.6.1.4.1.1466.115.121.1.15 stands for Directory String. A string in this syntax is encoded in the UTF-8 form of ISO 10646, which is a superset of Unicode. For more information, see RFC2252.

Viewing the new class using Directory Management Tool

You can use the Directory Management Tool (hereafter called DMT), which comes with IBM Secureway Directory V3.2.2. or V4.1, to modify portalUser object class.

After you change the V3.modifiedschema file, start Directory Server. In Windows, open the Services window. Select IBM Secureway Directory V3.2.2 (or IBM Directory V 4.1 ) and click Start.

Tip: The service must start without errors. If it gives errors, re-copy the V3.modifiedschema file, and try again. You can also start Directory Server by going to the /bin directory and entering: slapd. (Slapd is an executable file on Windows and Unix, which you can use to start the LDAP Service.)

After the service has started:

1. To open the Directory Management Tool, select Start -> Programs ->IBM Secureway Directory V3.2.2 (or IBM Directory Server V4.1)->Directory Management Tool .
2. Click Directory Management Tool . You see the message: Retrieving Server schema.
3. Click Rebind.
4. Select the Authenticated radio button and enter the Administrator User DN and password, as shown in Figure 3.
5. Click OK to login (often called Bind in LDAP terminology) to LDAP as the administrator.
6. Expand the Schema -> Object classes on the left pane.
7. Click on View object classes. On the right navigational pane, you see a list of all object classes. Keep scrolling down until you see portalUser.
8. Expand portalUser. You see the attributes that you added to the V3.modifiedschema file. You can view the optional attributes accountNumber, insuranceID and portalUserRole, the description of this object class, and its Superior object class.
   Figure 4. portalUser object class in DMT
   
   

Back to top

Creating the LDAP entries

The directory server uses the LDAP Data Interchange Format (hereafter called LDIF) to describe, in text format, a directory and directory entries. LDIF is commonly used to initially build a directory database or to add large numbers of entries to the directory all at once. In addition, LDIF is used to describe changes to directory entries.

In this part, you:

1. Examine the LDIF file format
2. Create the Suffix dc=xyz,dc=com
3. Create an LDIF file for running our samples
4. Import this LDIF file into our LDAP using the Web Administration GUI or the command line tool
5. View the added entries

Examining the LDIF file format

LDIF consists of one or more entries separated by a blank line. Each LDIF entry consists of an optional entry ID, a required distinguished name, one or more object classes, and multiple attribute definitions. The basic form of a directory entry is:

dn: <distinguished name> objectClass: <
object class>... : : ...

For example, the Groups entry in LDIF is :

dn: ou=Groups,dc=xyz,dc=com objectclass: organizationalUnit objectclass: 
top description: Container for group information ou: Groups

And, the PortalGroups entry in LDIF is:

dn: ou=PortalGroups,ou=Groups,dc=xyz,dc=com
objectclass: organizationalUnit objectclass: top ou:
PortalGroups
			

Create the Suffix dc=xyz, dc=com

Before you can import any entries in LDAP, you have to create the suffix. This is important as the suffix is the topmost or the highest entry stored by the Server. We will define a valid suffix through the use of the attribute type "dc", which is short for "domain component" You will use the Web Administration Console of IBM Directory to add the suffix dc=xyz, dc=com.

First, you start the Web server and the IBM Directory.

1. In Windows, open Services. Select IBM HTTP Server, and click Start.
2. Open the following URL in your browser: http://server.domain.suffix/ldap
3. Login with the administrator's ID and password. In this example, we use cn=admin and password is ldap.
4. On the Left navigation pane, click on Settings and then on Suffixes.
5. At the Suffix DN input box, enter dc=xyz,dc=com and click Update . You should see dc=xyz,dc=com in the list of Current server suffixes, as shown in Figure 5.
6. Click on restart the server , so that the newly added suffixes take effect. You have completed adding the suffix.

Create an LDIF File for running our samples

Next, you create the LDAP schema that you will use later to configure WebSphere Portal Server. If you already have WebSphere Portal Server installed with the suffix dc=xyz,dc=com , you might might have the following entries in LDAP:

uid=wpsadmin,cn=users,dc=xyz,dc=com uid=wpsbind,cn=users,dc=xyz,
dc=com cn=wpsadmins,cn=groups,dc=xyz,dc=com

You can verify this by:

1. Opening the DMT.
2. On the left navigational pane of the DMT, expand Directory tree.
3. Click on Browse tree.
4. On the right pane, you have to expand the suffix dc=xyz,dc=com to view all the entries.

If you do not have these entries, download ldapexamples.zip and extract WebSpherePortalLDAPEntries.ldif.

Figure 1 shows the hierarchical structure of the DIT that is needed at XYZ Technologies and the portalUser entries (uid=portaluser1, uid = portaluser2). We will create this DIT, including the following 7 entries:

dn: ou=Groups,dc=xyz,dc=com dn: ou=PortalGroups,ou=Groups,dc=xyz,dc=com dn:
cn=humanresources,ou=PortalGroups,ou=Groups,dc=xyz,dc=com dn: cn=accounts,
ou=PortalGroups,ou=Groups,dc=xyz,dc=com dn: cn=baseballTeam,ou=PortalGroups,
ou=Groups,dc=xyz,dc=com uid=portaluser1,cn=users,dc=xyz,dc=com uid=portaluser2,
cn=users,dc=xyz,dc=com

Importing LDIF files

Now you import the LDIF file so you can run the samples. If you have not already done so, download ldapexamples.zip. Extract portalusers.ldif from it.

To import the LDIF files, you can either use the Web Administration GUI or the command line tools. In our scenario, you use the GUI.

1. Login to the Web Administration Console.
2. If you are using Directory Sever V4.1, you must stop the LDAP Server before importing LDIF Files. If your LDAP server is running, on the left pane, go to Current state: Start/Stop and click Stop. (You do not have to stop the server if you are using Directory Sever V3.2.2).
3. Select Database -> Import LDIF.
4. Enter the complete path and file name where you extracted the two LDIF files.
5. Click on import and import portalusers.ldif.
   Repeat this process, if necessary, for WebSpherePortalLDAPEntries.ldif. If the entries have been added successfully, you will get a message saying that 7 entries have been added out of 7 attempted.
6. After importing the files, click Clear Results and restart Server.

Viewing the added Entries

1. Restart the LDAP Server after adding the entries.
2. Start the DMT.
3. Rebind as authenticated user.
4. You can view the entries by expanding Directory tree:
   In the left pane, click Browse Tree; in the right pane, expand dc=xyz,dc=com. You see the entries that you added in the LDIF files.
5. Double-click on cn=hr and you see that the member attribute has uid=portaluser1,cn=users,dc=xyz,dc=com in it.

Summary

So far, you have created a custom object class, called portalUser and added that class to the LDAP schema. You created the Directory Tree and populated the Directory Tree by importing an LDIF file using the Web Administration console. Finally, you opened the Directory Management Tool to view the entries.

Back to top

Configuring WebSphere Portal

The rest of this article tells you how to configure WebSphere Portal to authenticate and authorize users of the custom class you created above.

Member Services in WebSphere Portal

The component of WebSphere Portal that is used to manage users and groups is called Member Services. During installation, WebSphere Portal generates configuration parameters for Member Services and stores them in was_root\lib\app\xml\wms.xml. You can manually edit this file to modify the initial configuration settings.

The following entries exist in the wms.xml configuration file for Member Services.

Configure WebSphere Portal to use the custom LDAP schema created in Part1

By default, WebSphere Portal uses the groupOfUniqueNames object class for its groups. Instead, you need to configure WebSphere Portal to look at the accessRole object class for its groups. You can then view the groups that you created earlier in WebSphere Portal and assign entitlements to the them.

1. First, create a backup of your existing wms.xml file, and name it wms.xml.orig.
2. Locate the following section of thecode in wms.xml.
3. Using the table below, change the settings for the specified attributes.
4. Save wms.xml, and start WebSphere Portal, using the WebSphere Administration Console.
5. After portal server starts, go to the http://server.domain.suffix/wps/myportal URL and login as wpsadmin.
6. Select Portal Administration place from the list of dropdowns on the upper left corner.
7. Click on the Security tab.
8. On the Access Control List, make sure that the radio button for Selected users and groups is checked.
9. Click on Get groups and users. The Search For Groups radio button is selected by default and use a wildcard (*) for the name.
10. Click Go. You see the groups: accounts, baseballTeam, and human resources, which are the groups you added earlier.

Now you can select any of the groups, add them to the list, and assign entitlements.

Configure WebSphere Portal to use portalUser object class

WebSphere Portal uses the inetOrgPerson object class, by default. Now you will configure it with the portalUser schema that you created earelier. First, you need to configure the search filter within WebSphere Portal and WebSphere Application Server to look at the portalUser object class.

The portalUser object class has the following additional attributes:

• AccountNumber: A String attribute that has the accountNumber.
• InsuranceId: A String Attribute that has the employee's life insurance account number.
• Role: A multi-valued string attribute. It lists the groups in which this employee is included. For example, if the employee is in 2 groups called humanresources and baseballteam, then Role has the value: humanresources, baseballteam.

Recall that earlier you added the object class to the IBM Directory Server and also added the entries. Now you will view the user entries that you added.

WebSphere Portal uses Member Services to store the information about the Users and Groups. In order to modify the object class for the users, we will modify the same file you modified in the last section: /lib/app/xml/wms.xml file.

Locate the following in wms.xml file:

userObjectClass="top;inetOrgPerson"
userDefaultBase="cn=users,dc=xyz,dc=com"
userSearchBase="cn=users,dc=xyz,dc=com"

Because the portalUser object class inherits from inetOrgPerson, you do not need to edit the userObjectClass="top;inetOrgPerson" attribute. It will display all LDAP Entries having the object class as inetOrgPerson and all the classes that inherit from it.

You repeat the same sort of process that you did when you configured the groups.

1. Save the wms.xml file file.
2. Start up WebSphere Portal Server.
3. After the portal server starts, go to http://server.domain.suffix/wps/myportal and login as wpsadmin.
4. Select Portal Administration place.
5. Click on the Security tab.
6. On the Access Control List, select Search for users and use a wilcard (*) for the name.
7. Click Go.

You can now select an uid and assign permissions to it as follows:

1. Select any entry from the search results by clicking on it.
2. Add it to the list by clicking on Add to list.
3. Click OK.( You can also select multiple entries from the search results.)
4. In the dropdown for the Select the objects for permissions, you see that portlets is selected by default.
5. Ensure that the Show All radio button is selected.
6. Click on Go.

You see the list of portlets displayed along with the access permissions for uid=portaluser1 (that was selected in 4.3.5) for each portlet. Note that the uid=portaluser1 has edit access to the World Clock, Reminder, and Quick Links and view access to Welcome and few other portlets by default. Why is this so?

There is a special group called "All Authenticated Users". Any users that come in search results within portal are a member of this special group. You can view the permissions of this group by selecting Special Groups.

In Figure 11, the radio button is selected for Selected Groups and users. On the same screen, select the radio button for Special groups, select All Authenticated Users from the dropdown, and then click Go. All the portlets and the permissions for the Special Group All Authenticated Users display.

Now let's revisit the assignment of permissions.

1. After the list of portlets is displayed, select the required permission, and then click Save.
2. Logout and login as portaluser1 with password test.

You see the portlets that portaluser1 can access.

Back to top

Conclusion

This article demonstrated when to consider modifying the LDAP schema. You learned about the following:

• The Member Services component of WebSphere Portal
• Configuration of the attributes in WebSphere Portal to use the LDAP schema that we created earlier article for groups
• Configuration of WebSphere Portal to use the LDAP schema that you created in the first part of the article for the users
• Manage users and groups within WebSphere Portal to assign entitlements to users and groups

Back to top

Download

Name	Size	Download method
PrivacyManagerPortlet.zip	298KB	FTP|HTTP

Information about download methods

Resources

• WebSphere Portal Server V4.1 AIX 5L Installation
  
  
• WebSphere Portal Server V4.1 Windows 2000 Installation
  
  
• RFC 2251
  
  
• RFC 2252
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• When should you modify LDAP schema?
• Scenario: Creating a custom object class
• Creating the LDAP entries
• Configuring WebSphere Portal
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

With the no-charge DB2 Express-C, pureXML and evolving your XML schemas you can easily increase development and application performance.

---

• Try: Download a free trial version of DB2 Express-C, which includes pureXML technology that is ideally suited for managing XML schema and relational data.
• Article: See how to use DB2's pureXML schema evolution capabilities, that evolve schemas without making any changes to your applications.
• Tutorial: This tutorial shows you how using a native DB2 XML database enables changes in an existing XML schema to also appear in your application code.
• Demo: This demo shows you how easy it is to create a DB2 database for storing XML data.
• Buy: DB2 9 for Linux, UNIX and Windows

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers