0701 ilechko ltr

IBM WebSphere Developer Technical Journal:Expand your user registry options with a federatedrepository in WebSphere Application Server V6.1Using the Virtual Member Manager

Skill Level: Intermediate

Paul Ilechko ([email protected])Senior Solutions ArchitectIBM

Vikram Desai ([email protected])Solutions ArchitectIBM

24 Jan 2007

IBM® WebSphere® Application Server V6.1 offers a new federated user repositoryfeature that makes it easy for you to access and maintain user data in multiplerepositories, particularly since this capability is achieved by configuration (instead ofcoding) with the new Virtual Member Manager utility.

From the IBM WebSphere Developer Technical Journal.

Introduction

Before now, the support in IBM WebSphere Application Server for environmentswhere user information was stored in multiple independent user registries wassomewhat limited. Prior to Version 6.1, the only registry options available were:

• Local operating system registry.

• A single, standalone Lightweight Directory Access Protocol (LDAP)

Expand your user registry options with a federated repository in WebSphere Application Server V6.1© Copyright IBM Corporation 1994, 2006. All rights reserved. of 42

mailto:[email protected]

mailto:[email protected]

http://www.ibm.com/websphere/developerworks/websphere/techjournal/

http://www.ibm.com/legal/copytrade.shtml

registry.

• A single implementation of the Custom User Registry interface.

It is possible to implement a Custom User Registry that enables access to multipleother registries, but this can involve a significant development effort that ultimatelywould only support read-only operations.

WebSphere Application Server V6.1 provides a new option: a federated userrepository. This feature makes it much simpler to use multiple repositories, sincethis capability is achieved through configuration -- rather than development -- withthe use of the new Virtual Member Manager (VMM).

In essence, this feature provides the ability to map entries from multiple individualuser repositories into a single virtual repository. The federated repository consists ofa single named realm, which is a set of independent user repositories. Eachrepository may be an entire external repository or, in the case of LDAP, a subtreewithin that repository. The root of each repository is mapped to something called abase entry within the federated repository, which is basically a starting point withinthe hierarchical namespace of the virtual realm. You will understand this moreclearly later when we describe how to configure the VMM.

What we are discussing here is the idea of one logical registry containing users frommultiple underlying repositories. To the WebSphere Application Server runtime,there is still only one registry, and thus, all applications in the cell still share this onesingle registry. Refer to Figure 1.

Figure 1. Registries seen by WebSphere Application Server

developerWorks® ibm.com/developerWorks

Expand your user registry options with a federated repository in WebSphere Application Server V6.1 of 42 © Copyright IBM Corporation 1994, 2006. All rights reserved.


The Virtual Member Manager is a new component that incorporates some of theexisting capabilities in the WebSphere registry, the WebSphere Member Manager(from WebSphere Portal), and a subset of the secure administrations functions. Thegoals of the VMM are to:

• Provide a repository-independent programming interface.

• Support various pluggable repositories.

• Provide the ability for users to achieve a single view of their own multiplerepositories in a federated model.

Careful readers might notice that a custom repository is not includedin the list of what can make up a federated repository realm. As itexists today, VMM does not support custom repositories. Therefore,if you need a custom repository, you cannot use VMM. Instead, youmust write a custom user registry, the same as you needed to do inprevious releases. We expect this restriction to be eliminated in the

ibm.com/developerWorks developerWorks®



near future.

A federated repository contains a realm that can consist of identities in:

• The file-based repository that is built into the system.

• One or more external LDAP repositories.

• A JDBC accessible database repository.

Unlike with the local operating system, standalone LDAP directory, or customregistry options, federated repositories provide user and group management withread and write capabilities. When you configure federated repositories, you can add,create, and delete users and groups using one of these:

• User/group management application programming interfaces (API).

• Administrative console.

• wsadmin commands.

In this article, you will learn how to set up and use the basic capabilities of the VirtualMember Manager by configuring a standalone WebSphere Application Server V6.1instance to run with a federated repository consisting of file, database, and LDAPrepositories. We will progressively add repositories to the federated repository anddemonstrate the ability to view the different repositories as a logically unifiedrepository for user and group management. You will also learn how to configureLDAP group membership options.

Limitations of federated repositories

• Only one user repository can be configured to be the target for creatingusers/groups from the administration console. By default, this is the filerepository, but this can be changed, as you will see later. You can use theuser and group management wsadmin commands to create users/groupsin other repositories, or use native tools for those repositories.

• The username (for example, LDAP uid) must be unique across thedifferent repositories. For example, users cannot have the same uid indifferent LDAP directories, even under different org structures.

• If one or more repository in the federation is down, you will not be able toauthenticate (even as an admin), regardless of which repository yourparticular ID is stored in. The VMM component always checks all



http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/topic/com.ibm.websphere.javadoc.doc/vmm/overview-summary.html

http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.wim.doc.en/usermanagementcommands.html


repositories before letting an authentication to succeed.

• Although VMM has the capability to support multiple realms, WebSphereApplication Server only supports a single realm at this time. This isdefined at the cell level and is shared by all applications.

• Additional limitations are listed in the WebSphere Application Server V6.1Information Center.

Configure a federated repository

By default, WebSphere Application Server V6.1 enables administrative securityduring installation. Unless this option is disabled, the file based repository is usedautomatically as the user registry.

We will begin our exercise by configuring the built-in file-based repository, with theassumption that administrative security was disabled during installation. If theadministrative security option was not disabled during installation then you wouldhave provided the admin user name and password during installation, as shown inFigure 2.

Figure 2. Enable administrative security



http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/rwim_limitations.html


We will assume this option was disabled during installation so we can show you howto configure federated repositories from scratch. (Under typical circumstances youshould NOT disable administrative security during installation.)

To work with the security configuration, access the WebSphere Application Serveradministration console and navigate to Security => Secure administration,applications and infrastructure. For the purpose of this article, we will onlyconfigure administrative security. Otherwise, application security should also alwaysbe enabled so your applications can leverage WebSphere Application Serversecurity.

The next sections will show how to set up a federated repository using:

1. The built-in file-based repository

2. A database repository

3. An LDAP repository (using Windows® Active Directory and IBM Tivoli®Directory Server as examples).




Set up a federated repository using the built-in file-basedrepository

Here, you will configure the federated repository using the default file-basedrepository, and then enable administrative security.

1. On the Secure administration, applications, and infrastructure dialog,select Federated repositories from the Available realm definitions dropdown, and click Configure (Figure 3).

Figure 3. Begin Federated repository setup

2. The federated repository consists of a single realm that contains severalbase entries. A realm within WebSphere Application Server is an instanceof a user registry; the realm is the top level logical entry that representsthe user registry. In a federated repository configuration, the federatedrepository instance is the realm. By default, the Realm name isdefaultWIMFileBasedRealm (Figure 4). This name can be changed to




any appropriate name for your environment; it does not need to be sameas the realm's base entry. Throughout this article, we will leave the realmname as the default, although in practice you will want to change this tosomething more appropriate.

3. A base entry identifies the root (or starting point) for a set of objects withinthat realm; within a realm, there can be several base entries. Each baseentry is mapped to the root of a directory tree in a given repository. In flatrepository, such as a file-based repository, a base entry is the root of allthe entries within the repository. In a hierarchical repository, like LDAP, abase entry is mapped to an entry in the directory information tree thatidentifies the top of a subtree in the DIT. (We will explain more when welook at LDAP repositories.) By default, there is a single base entrycorresponding to the file-based repository with the base entry:o=defaultWIMFileBasedRealm (Figure 4). This is the identifier for theroot of the file-based repository. All users created under this base entrywill have a fully qualified name of uid=<UID>,o=defaultWIMFileBasedRealm. Since the file-based repository is nothierarchical, all objects within the file repository will be stored under thisbase entry

4. WebSphere Application Server V6.1 distinguishes between the useridentities for administrators who manage the environment, and serveridentities for authenticating server to server communications. In mostcases, server identities are automatically generated and are not stored ina repository. However, if you are adding a Version 5.0.x or 6.0.x node to aVersion 6.1 cell, you must ensure that the Version 5.x or Version 6.0.xserver identity and password are defined in the repository for this cell. Insuch a case, you would enter the server user identity and password(Figure 4). Since we are in a single server environment with only oneWebSphere Application Server V6.1 node, we will choose theautomatically-generated server identity. We will create a user called"wasadmin" to be the administrative user, which will be created andstored in the file based repository. Click OK.

Figure 4. Configure realm properties




5. Enter and confirm the password for the administrative user ID, then OK(Figure 5).

Figure 5. Select password for administrative user ID




6. The basic federated repository configuration is now complete. Next, youcan configure WebSphere Application Server to use administrativesecurity. To do so (Figure 6):

a. Check Enable administrative security.

b. Application security and Java 2 security are both checked bydefault. To keep this example simplistic, uncheck Java 2 security.

c. Make sure that the value of Current realm definition is set toFederated repositories. If you need to change this value, selectFederated repositories from the Available realm definitionsdrop-down list, then select Set as current. This will change thevalue of Current realm definition.

Figure 6. Enable administrative security




7. Click on Apply, save the changes, and then restart the server.Administrative security is now enabled. The file repository is configuredand users and groups can be added to the file repository through theadmin console.

For the curious, the file repository is stored under your profile in:$WAS_HOME\profiles\<profileName>\config\cells\<cellName>\fileRegistry.xml.This file contains user and group identifiers, including the encryptedpasswords for the user entries. The passwords for a user isencrypted using a one way hash by applying the message digestalgorithm specified in the VMM configuration file (wimconfig.xml).The default value for the message digest algorithm is SHA-1. Thealgorithm can be updated to a different value using the wsadmincommand updateIdMgrFileRepository. One of the parameters youcan use with this command is the messageDigest Algorithm.

8. To use the admin console again, you will need to log into it using theadministrative user ID and password that you just configured.

9. You can now view the users in the file repository by navigating to theUsers and Groups section of the admin console. Go to the ManageUsers pane and search for existing users; search with a wildcard value *to see users in the default file repository (Figure 7).




Figure 7. Search for users with wildcard value

10. From the admin console, you have the ability to create and removegroups, add and delete users, and modify group memberships for users.You will now add a user called userFileRegistry to the registry. Todo this, simple select Create and enter the required information. Whenyou are finished, the Search for users screen will show two users (Figure8).

Figure 8. Create a new user

As a convention to make the screen shots in this article easier to understand andfollow, user names will be configured with the format ofuser<Registryname>Registry. This will make it easy to identify the repository in




which the user is stored. This naming convention is for the purposes of this articleonly and is not required by WebSphere Application Server V6.1 when using afederated repository.

Set up a federated repository using a database repository

You will now configure a database repository, in addition to the file-based repositoryyou created in the previous section.

In the Virtual Member Manager, a database repository is a database with a specificpredefined schema that supports the standard VMM entity types of PersonAccount,Group, and OrgContainer. It is possible to extend the schema with user-definedentity types, but that topic is beyond the scope of this article. There is alsoextensibility to the schema in that you are able to add additional user attributes tothe predefined entities. What is not supported is the ability to use an existingapplication database that contains user and group information.

The database repository also has the ability to support groups that contain users inother repositories, but this is only true for the database repository; file based andLDAP repositories do not have this capability. (See the WebSphere ApplicationServer Information Center for details on how to configure the repositoriesForGroupsparameter using the updateIdMgrRepository command.)

As a precaution, backup the wimconfig.xml file before configuringadditional repositories. If it is necessary to rollback changes madeduring a new repository configuration, you should be able to do thisby replacing the backup version on wimconfig.xml. However,exercise all due caution, as this is not a supported mechanism.

At the time of publication, the database repository cannot be configured through theadmin console; it can be only configured using the command line wsadmincommands. In this section, you will see how to configure the database userrepository using an IBM DB2® database. (If desired, any other database supportedby WebSphere Application Server can be used instead, and the steps will besimilar.) All changes pertaining to the configuration of a new repository are made tothe file wimconfig.xml located in your profile's configuration directory:$WAS_HOME\profiles\<profileName>\config\cells\<cellName>\wim\config.

To configure a DB2 database repository using the JDBC type 4 driver:

1. Create a DB2 database. The tables for the database repository will becreated by the wsadmin commands. For this configuration we created adatabase named wimDB.



http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp



2. Configure a DB2 datasource (using the admin console or wsadmincommands) with the JNDI name jdbc/wimDB. This datasource will beused for configuring the federated repository accessing this database.(See Configuring a data source using the administrative console in theInformation Center.)

If you encounter a problem related to DB2 classes not found in theclasspath while running the wsadmin commands to configure thedatabase repository, check to make sure the WebSphere ApplicationServer variable DB2_JDBC_DRIVER_PATH is set correctly.

3. Set up the repository by using this wsadmin command to create thewimDB tables (replace $WAS_HOME with the actual value of theWAS_HOME environment variable):

wsadmin>$AdminTask setupIdMgrDBTables {-schemaLocation "$WAS_HOME\etc\wim\setup"-dbPropXML "$WAS_HOME \etc\wim\setup\wimdbproperties.xml" -databaseType db2 -dbURLjdbc:db2:wimDB -dbDriver com.ibm.db2.jcc.DB2Driver -dbAdminId <db2User> -dbAdminPassword<db2UserPwd> -dn o=database.org -reportSqlError true}

Under the schemaLocation $WAS_HOME\etc\wim\setup you will findthe database-specific SQL files for creating the wimDB tables. For DB2,the SQL files are located under$WAS_HOME\etc\wim\setup\database\db2. Be aware that the -dnentry in the command defines the root for the distinguished names of theobjects to be stored in the database repository. This is not necessarily thesame as the base entry for the database repository in the federation. Userand groups within the database repository will be created under this rootdistinguished name, which can be whatever you want it to be(o=database.org is an arbitrary value chosen for the purposes of thisarticle).

Successful completion of this command will create the tables shown inFigure 9 (as displayed in the DB2 control center).

Figure 9. Database tables created



http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/tdat_ccrtpds.html


4. Register the DB repository with the VMM using this wsadmin command:

wsadmin>$AdminTask createIdMgrDBRepository {-id DB2Repos -dataSourceName jdbc/wimDB-databaseType db2 -dbURL jdbc:db2:wimDB -JDBCDriverClass com.ibm.db2.jcc.DB2Driver-dbAdminId <db2User> -dbAdminPassword <db2UserPwd>}

In this command, the ID used here (DB2Repos) is the repository identifierof this repository in the federated repository. (This will be clear when yousee it defined in Figure 10.) This command set the datasource namealong with the values required to access the database repository using adirect JDBC connection. This is needed, since there are situations inwhich the runtime might need to access the federated repository when nodatasource is available; in such a situation, direct JDBC access will beused.

5. Configure a base entry for this repository using this wsadmin command:

wsadmin>$AdminTask addIdMgrRepositoryBaseEntry {-id DB2Repos -name"o=database.org" –nameInRepository="o=database.org" }

The base entry name here, "o=database.org," is same as the valueof the -dn option of the setupIdMgrDBTables command. In this case,




we used the same name for the base entry name in the federatedrepository (-name), as that in the actual database repository(-nameInRepository). This is not required; the base name in thefederated repository can be set to a different name than the actualrepository root DN.

6. Add the new baseEntry to the default or base realm:

wsadmin>$AdminTask addIdMgrRealmBaseEntry {-name "defaultWIMFileBasedRealm" -baseEntry"o=database.org"}

7. Save the configuration:

wsadmin>$AdminConfig save

8. Quit wsadmin and restart the server. The database repository is nowconfigured.

9. When you log into the admin console, you will see that the databaserepository is now part of the federation (Figure 10).

Figure 10. Database repository has been added to the federation




Also, on the Manage repositories panel (Figure 11), the databaserepository shows up as a defined repository. (Removing a repository fromthe federation does not delete the repository definition; that is a separatestep.)

Figure 11. Manage repositories




10. There are no users in the database repository yet. When new users arecreated in the admin console, they are also created in the file basedrepository. However, you need to make a configuration change if you alsowant to be able to add users to the database repository from the console.Let's now look at how to update the federated repository configuration inthe admin console so that when users are created they also get created inthe database repository rather than in the default file-based repository.

Navigate to the federated repository configuration panel at Secureadministration, applications, and infrastructure => Available RealmDefinitions => Configure and select Supported entity types (Figure12).

Figure 12. Supported entity types




11. To modify default user creation so that it uses the database repository,the base entry for the default parent has to be changed to the databaserepository base entry (that is, o=database.org). In this example,change it for the PersonAccount which will enable you to add users to thedatabase repository. (We won't show the details, but you would clearlywant to do this for Groups as well.) Select PersonAccount.

Figure 13. PersonAccount properties

12. Change the value of Base entry for the default parent (Figure 13) too=database.org and Apply.

Figure 14. Change base entry value




13. Save the changes shown in Figure 14 and restart the server for the baseentry change to take effect.

When new users are added using the admin console, they can be placedin only one repository: whichever repository is the current default asdefined by the base entry you set. If you need to add users to otherrepositories, use the native tools available to you with those products.

14. Now, create a user with user ID of userDatabaseRegistry byselecting Users and groups => Manage users => Create, as shownearlier. When done, users from both the file and database repository aredisplayed (Figure 15).

Figure 15. Search for users

You have seen how to configure a database repository and make changes such thatnew users and groups are created in the database repository, instead of the defaultfile-based repository. In the next section, you will see how the federated repositorycan be configured to add users and groups to LDAP.

Set up a federated repository using an LDAP repository

You will now add two LDAP directories to the configured federated repository, whichso far contains two repositories: the default file-based repository and a databaserepository.

The basic steps for adding an LDAP directory to a federated configuration are:




1. Add the LDAP directory to the list of repositories available forconfiguration for the federated repository.

2. Add baseEntries rooted at a particular search base within the LDAPdirectory. Multiple base entries can be added with different search basesfor a single LDAP directory.

The two LDAP directories we will add are:

• Windows Active Directory LDAP

• IBM Tivoli Directory Server.

Add Active Directory LDAP

To add the Active Directory LDAP to the list of available repositories:

1. Login to the admin console, then navigate to Security => Secureadministration, applications, and infrastructure => Federatedrepositories => Manage repositories, and select Add.

Figure 16. Add LDAP repository




2. Enter or select the values shown in Figure 16, then select OK and savethe configuration. This adds the Active Directory LDAP to the list offederated repositories available for configuration. You will notice that thisconfiguration lets you specify an LDAP failover server. If you wish, youcan list multiple LDAP server replicas by IP address or hostname, and theapplication servers will automatically failover to one of the backup serversif the primary fails. There are additional properties you can configure forthe added LDAP; we will look at those later when we discusscustomization and configuration of LDAP attributes.

3. Now that the repository has been added to the list of federatedrepositories, a base entry needs to be configured to point to a subtree(search base) in the LDAP directory. The base entry enables the entriesin the LDAP subtree to become part of the federated repository realm.

To configure a base entry in the admin console, navigate to Security =>




Secure administration, applications and infrastructure =>Availablerealm definitions => Federated repositories => Configure.

4. The already configured base entries in the realm are shown; in this case,you will see the base entries corresponding to the file-based anddatabase repositories (Figure 17). Now you will add an entry from theActive Directory LDAP. Select Add Base entry to Realm.

Figure 17. Existing base entries

5. On the following screen (Figure 18), select TestADS for the Repositoryname, indicating the name of the previously configured Active DirectoryLDAP. Add the distinguished name of the base entry in the federatedrepository and the base distinguished name in the Active Directory LDAPdirectory to specify the search root. The former name defines a logicalroot entry for this particular repository in the virtual realm, the latter nameis the root of the subtree within the LDAP for the set of objects that willbecome part of the federated repository. What you have actually donehere is define a mapping between and LDAP subtree root and a virtualrealm root (base) entry, so that all objects from the LDAP under thatsubtree appear to be in the logical realm under the defined base entry.

If "Distinguished name of a base entry in this repository" is left blank, thenthe base entry will be mapped to the root ("") of the LDAP server and allthe operations will be performed at root. For most LDAP servers this willnot work. Thus, you should contact your LDAP administrator to determinethe correct root for the directory.

Figure 18. Repository reference




6. When you save this, the base entries shown in Figure 19 will display inthe federated repositories.

Figure 19. Repositories in this realm

The search base specified is dc=testadsserver,dc=local. In thisarticle, we specify only one subtree for the configured Active DirectoryLDAP. If you want additional subtrees configured, add additional baseentries with appropriate subtree roots.




7. Restart the server.

8. Now, if you go to the Users and Groups area of the console and searchfor all users, you will see users from the file-based repository, thedatabase repository, and the Active Directory LDAP server. Note the DNof the LDAP users: it's a concatenation of the actual DN of the user in theLDAP and the base entry that you defined to the federated repository.Note that the subtree root in the actual LDAP(dc=testadsserver,dc=local) does not show up in the user name;instead, the base entry to which this was mapped in the federatedrepository is shown. The unique ID of the user is the user ID plus thebase entry to ensure uniqueness across repositories within the federation;however, this does not eliminate the requirement that all user IDs acrossall repositories in the federation must be unique.

Figure 20. All users in all repositories

A search on all users shows users from all the repositories; notice theuserADSLDAPRegistry, which was created on the ADS server. Similarly,a group search will show groups from all the repositories. Clicking on anindividual user gives more information about the user, as well as thegroups the user belongs to. For example, Administrator is a user in theActive Directory LDAP; if you click on this user ID, Figure 21 will display.

Figure 21. User detail




If you click on the Groups tab, Figure 22 will display.

Figure 22. Group detail




Add IBM Tivoli Directory Server

With Active Directory LDAP added, we will now follow similar steps to add IBM TivoliDirectory Server to the list of directories.

1. Add a new repository through the admin console as before (Figure 23).

Figure 23. Add new repository




As in the case of Active Directory LDAP, all we need is the Primary hostname. Additional LDAP properties need to be configured, which will bediscussed later. After adding the IBM LDAP, four repositories will displayin the available federated repository list (Figure 24).

Figure 24. Available federated repositories




2. As in the case of Active Directory LDAP, to enable entries from the IBMLDAP to be available within the federated repository, at least one baseentry pointing to the base of a subtree needs to be configured. To add abase entry in the admin console, navigate to Security =>Secureadministration, applications and infrastructure =>Available realmdefinitions => Federated repositories => Configure, then select AddBase entry to Realm.

3. On the following panel (Figure 25), select ITDSLdap. Add appropriateDistinguished name in the federated repository (o=ITDSLdap) andcorresponding Base entry in the actual LDAP (dc=ibm, dc=com). Whenfinished, Apply the changes.

Figure 25. Configure IBM LDAP

The entries will be added under dc=ibm,dc=com within the IBM TivoliDirectory Server LDAP as a part of the federated repository under thebase entry distinguished name o=ITDSLdap, as shown in Figure 26.

Figure 26. Federated repositories




4. Restart the server. Now, a search for users will also show users from theIBM LDAP (Figure 27); the user userIBMLDAPRegistry was created inIBM Tivoli Directory Server using ITDS admin tools within (cn=users,dc=ibm, dc=com).

Figure 27. Search for all users




As with other directories, notice that the user IBMLDAPRegistry is qualified with thebase entry in the federated repository to provide the realm unique name.

Configuration and customization of LDAP attributes

In the above sections, you added the LDAP directories with default values andwithout customizing any LDAP attributes. Here, we will look at additional propertiesthat might need to be configured for LDAP when it is added as a part of federatedrepository. We say "might" because not all LDAP servers are the same. Differentimplementations use different object classes to specify user and group information,and different ways of defining group membership. It is therefore likely that the defaultvalues will not be adequate. Additional properties that are available are describedbelow, with an example of how to perform the additional configuration for the IBMLDAP directory.

When you add an LDAP to the federated repository, three links for additionalproperties display at the bottom of the configuration panel:

• Performance

Performance lets you set properties related to search timeouts andsearch result limits for configured LDAPs. Performance properties wouldbe configured while tuning the federated repository. (See Increasing the




performance of the federated repository configuration in the InformationCenter for more.)

• LDAP entity types

Out-of-the-box, the Virtual Member Manager component defines threeentity types that represent object types managed within the federatedrepository. These provide a way to map object types in differentrepositories into a common object model in the VMM. These entity typesare:

• Group -- the entity representing group-related objects in therepository; maps to group objects in LDAP.

• OrgContainer -- the entity representing organization-related objects;maps to organization objects in LDAP.

• PersonAccount -- the entity representing user-related object; mapsto person objects in LDAP.

For example, let's look at the entity type and group object configuration forthe IBM LDAP. Groups within IBM LDAP are typically stored under objectclasses "groupOfNames" and "groupOfUniqueNames". The default valuefor entity type group is objectclass groupOfNames. You therefore need toadd the ObjectClass groupOfUniqueNames to ensure that all groupobjects defined with this objectclass within the LDAP are correctlymapped to VMM groups.

a. In the admin console, navigate to Secure administration,applications, and infrastructure => Federated repositories =>Manage repositories => ITDSLdap => LDAP entity types.

b. Select Group and edit the Object classes field to have a value ofgroupOfNames;groupOfUniqueNames. Note the entries areseparated by a semicolon (Figure 28).

Figure 28. Configure Group entity



http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/twim_performance.html


c. You can also specify Search bases and a Search filter on thisscreen. The search bases specified must be subtrees of the baseentry in the repository. Here, the base entry is dc=ibm,dc=com.The search filter has to be a subtree of this entry in the LDAPdirectory. The search filter configuration specifies the LDAP searchfilter that is used to search this entity type. Using the LDAP searchfilter syntax, a valid search filter would be:(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)).

Additional details on mapping LDAP search filters is describedbelow.

d. Save the Group entity type configuration with the added Objectclasses; the configured object classes for the entity type are shownin Figure 29.

Figure 29. Configured object classes

• Group attribute definition

For the Virtual Member Manager to understand which groups an object is




a member of, you need to define the associated membership attribute forthe object class.

a. The attributes for an ObjectClass are added under Group attributedefinition => Member attributes. In the admin console, navigateto Secure administration, applications, and infrastructure =>Federated repositories => Manage repositories => ITDSLdapand select Group attribute definition.

Figure 30. Group membership

b. The Name of group membership attribute (Figure 30) specifies anLDAP attribute indicating the groups to which an entry belongs.This entry depends on the LDAP being used. For IBM LDAP, thevalue is ibm-allGroups. Other LDAP server types will have theirown attribute that needs to be configured here. You can alsospecify whether nested and dynamic group membership is withinthe scope of the membership attribute. (This article does not coverdetails of these concepts.) Since not all LDAPs will have asupported attribute for defining group membership, this attribute isoptional. If the LDAP you use does support this attribute, be sure touse it to establish group membership and improve performance. Ifthe group membership attribute is not specified, the LDAPrepository can establish membership by searching all groups, butthe resulting performance will likely be much slower.

c. In addition to the group membership attribute name, you can alsospecify the scope of the group membership attribute. This valueindicates how the Virtual Member Manager can traverse throughthe LDAP directory to determine group membership. Depending onhow the LDAP directory actually manages information stored in this




attribute, one or more calls may be needed to determine all thegroups that the user is a member of. Specifying the scope canimprove the performance of such searches. For a given groupmembership attribute for a given LDAP, it is necessary to knowhow the given LDAP manages its membership attribute, and whatvalues this attribute will return. For example, for Active DirectoryLDAP, the scope of the memberOf attribute is Direct, that is, onlydirect parent groups of the user will be returned. To determine theNested groups of a user, the VMM must first get the direct groupsusing the memberOf attribute, then go through the returned groupsone by one and get their direct groups, and so on. This processresults in multiple calls to the Active Directory LDAP. To do thesame search for IBM Tivoli Directory Server LDAP usingibm-allGroups this elaborate searching is not required, sinceITDS maintains all groups, including nested and dynamic groupmemberships, using that attribute. Therefore, the scope for theattribute should be set to All so that the VMM knows not to makeadditional unnecessary calls.

d. Figure 30 also shows two Additional Properties that provide theability to define reverse linkage, which is how groups maintaininformation about their members, for both static and dynamicgroups. For a static group, the membership list is maintained onthe object itself as a list of members. For dynamic groups, what isactually maintained in the membership attribute is an LDAP searchfilter.

For each member object class that defines a group, such asgroupOfNames and groupOfUniqueNames, you can define thecorresponding member attribute for group membership. In ourscenario, the member attribute for the groupOfNames object classis member, which is present by default. You also need to add auniqueMember member attribute corresponding to thegroupOfUniqueNames object class. In the Additional Propertiessection, select Member Attributes, then New.

e. Add uniqueMember as a new Member name, andgroupOfUniqueNames for Object class. Leave the scope defaultvalue direct. When finished, the member attributes will appearas shown in Figure 31.

Figure 31. Member attributes




You could also have added member attributes for dynamic groups, butthat is beyond the scope of this article. However, you can define bothstatic and dynamic searches for the same object class if you have ahybrid group with both static and dynamic members.

Mapping LDAP search filters

The search filter for an entity type (group, PersonAccount, orgContainer) specifiesthe LDAP search filter that is used to search this entity type. The search filter syntaxis a subset of the standard LDAP filter. Some sample filter values in VMM are shownbelow and compared to query strings that could have been used in a standaloneWebSphere Application Server user registry configuration (without using a federatedrepository).

1. If you want to search by user ID within an LDAP subtree and limit yoursearch to Person objects, then the search filter used would be: ((uid =%v)(objectclass=Person)). In the VMM, this filter would need to bespecified differently, since the VMM does not support replacementparameters such as "%v". In the VMM, the filter to substitute uid with thespecified value is applied by the VMM runtime during login to theapplication server, according to the login properties specified for an LDAPconfigured in the federated repository.

For example, in Figure 16: while adding the Active Directory LDAP, theLogin properties field is specified to be "uid". During login, this translatesto a search filter "uid=<value>". If it is also necessary to limit the search toPerson objects, this would need to be specified in the search filter, in thePersonAccount entity type, as (objectclass=Person). For theconfigured Active Directory, this would be as shown as in Figure 32.

Figure 32. Modify search filter




Here, the filter (uid=%v) gets implicitly mapped in the VMM runtime.This search filter is potentially also re-mapped from VMM properties to therespective LDAP specific properties. This decoupling enables the use of astandard set of properties across a variety of different registries. In thisparticular example, the second level of mapping occurs within the VMM,where "uid" gets mapped to an LDAP specific attribute, before the searchstring is submitted to find the user to the actual LDAP. The mapping ofVMM properties to LDAP specific attributes is specified in the VMMconfiguration file wimconfig.xml.

The next example is of a specific filter for Active Directory that explainsthe mapping in more detail.

2. Next, we will look at a search filter specific to Active Directory LDAP andthe changes required to configure such a user search filter in the VMM.This example searches for a user account in an Active Directory LDAP bymatching the value in either the "sAMAccountName" or"userPrincipalName" attribute. Here, the LDAP search filter would be:(|(sAMAccountName=%v)(userPrincipalName=%v)).




Mapping this search string in VMM translates into mapping the ActiveDirectory attributes to properties that are recognized within the VMM.LDAP specific attributes are mapped in the VMM to VMM definedproperties, such as uid, cn, sn, and so on. This method provides a genericLDAP independent schema definition.

To perform this search, you do not actually need to specify a search filterfor the LDAP entity type PersonAccount. In fact, as shown in the previousexample, replacement expression "%v" is not supported in a search filterin the VMM. All you need to do is make sure that Active Directory userattributes "sAMAccountName" and "userPrincipalName" are mapped tovirtual member manager properties, and that these properties areconfigured in the Login Properties so that the search expression createdinternally by the runtime will perform the desired mapping. To do this:

a. In the wimconfig.xml file, you need to map Active Directory attribute"userPrincipalName" to VMM property "uid". Search for the sectionin the file where the Active Directory LDAP is configured and addthe <config:attribute> element for this mapping:

<config:repositories xsi:type="config:LdapRepositoryType"adapterClassName="com.ibm.ws.wim.adapter.ldap.LdapAdapter" id="testads"isExtIdUnique="true" supportAsyncMode="false"supportExternalName="false" supportPaging="false"supportSorting="false" supportTransactions="false" certificateFilter=""certificateMapMode="exactdn" ldapServerType="AD2003"translateRDN="false">

<config:baseEntries name="o=ads2003"nameInRepository="cn=users,dc=testadsserver,dc=local"/>

.....<config:attributeConfiguration>

...<config:attributes name="userPrincipalName"

propertyName="uid"><config:entityTypes>PersonAccount</config:entityTypes>

</config:attributes>...

</config:attributeConfiguration>...

</config:repositories>

b. Map Active Directory attribute "sAMAccountName" to virtualmember manager property "cn". As you did above, add thefollowing to the wimconfig.xml file:

<config:attributeConfiguration>...




<config:attributes name="sAMAccountName"propertyName="cn">

<config:entityTypes>PersonAccount</config:entityTypes></config:attributes>...

</config:attributeConfiguration>

3. Configure Login Properties to accept properties "uid" and "cn" byspecifying the value uid;cn. Now, during login to the application server,if the user ID value is "[email protected]" the search filter willsearch for "[email protected]" or"[email protected]". Since "uid" is mapped to"userPrincipalName" and "cn" is mapped to "sAMAccountName", theequivalent value of "[email protected]" or"[email protected]" is the search filterexecuted against the Active Directory LDAP.

4. For group search filters, "cn" is the VMM property used to map groupname. Again, for a search filter such as(&(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames))),the filter "cn=%v" is mapped implicitly by the VMM. The filter(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames))is specified in the entry for search filter for the group entity type.

Adding users and groups to LDAP based repository using theadmin console

To create users and groups in the WebSphere Application Server administrativeconsole and have them stored in your LDAP repository instead of the defaultfile-based repository, you need to make configuration changes similar to those youmade earlier to add users to the database repository. The base entry for the defaultparent needs to be changed to that configured for the LDAP repository. Forexample, for the configured IBM Tivoli Directory Server LDAP:

1. Navigate to Secure administration, applications, and infrastructure=> Federated repositories => Configure => Supported Entity Type.

2. Change PersonAccount to have BaseEntry cn=users,o=ITDSLdap(Figure 33).




Figure 33. Modify base entry

3. Save and restart the server. Now, users added through the admin consolewill be stored in the IBM LDAP.

Conclusion

You have now configured a federated repository with four independent repositories.From an administrative point of view, all the repositories must be available when theapplication server starts. It is also required that the user ID be unique across all userrepositories that are configured under the same federated repository configuration.When a user logs in, the Virtual Member Manager runtime searches each of therepositories for all of the occurrences of that user. If multiple instances of that userare found in the combined repositories, an error message is displayed.

To enable security for J2EE applications, ensure that the application security optionin the security configuration section inside the WebSphere Application Server adminconsole is checked (this option is checked by default).

Installed applications see the different repositories as a single logical repository.Users and groups from all repositories are available for mapping users and groupsto protected resources within the J2EE applications. For an example, try accessinghttp://<hostname>:9080/snoop. You should be able to login and authenticate toaccess this sample application as a user from any of the four configuredrepositories.

Acknowledgements

The authors would like to thanks Keys Botzum and Ranjan Kumar for all of theirassistance in reviewing the paper and making sure that it made sense and wastechnically accurate.




Resources

• WebSphere Application Server V6.1 Information Center

About the authors

Paul IlechkoPaul Ilechko is a Senior Solutions Architect with IBM Software Services forWebSphere. Mr. Ilechko has over 25 years of experience in the IT Industry, including abackground in both mainframe and distributed technologies. He has been involved withWebSphere and J2EE technology almost since their inception. His primary goal is tohelp IBM clients be successful with these products. Mr. Ilechko has a B.Sc. inMathematics from the University of London.

Vikram DesaiVikram Desai is an Architect with IBM Business Partner Technical Enablement. Hehas worked with several IBM Business Partners to enable them on WebSpherePlatform. Previously he has worked as part of development teams for WebSpherePortal, NextWeb, Federated NAS, WebSphere Application Server, Encina++/Encina.





0701 ilechko ltr

Documents