IBM WebSphere Developer Technical Journal: Expand your user registry options with a federated repository in WebSphere Application Server V6.

Transcription

1 IBM WebSphere Developer Technical Journal: Expand your user registry options with a federated repository in WebSphere Application Server V6.1 Using the Virtual Member Manager Skill Level: Intermediate Paul Ilechko (paul.ilechko@us.ibm.com) Senior Solutions Architect IBM Vikram Desai (vdesai@us.ibm.com) Solutions Architect IBM 24 Jan 2007 IBM WebSphere Application Server V6.1 offers a new federated user repository feature that makes it easy for you to access and maintain user data in multiple repositories, particularly since this capability is achieved by configuration (instead of coding) 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 environments where user information was stored in multiple independent user registries was somewhat limited. Prior to Version 6.1, the only registry options available were: Local operating system registry. A single, standalone Lightweight Directory Access Protocol (LDAP) Page 1 of 42

2 registry. A single implementation of the Custom User Registry interface. It is possible to implement a Custom User Registry that enables access to multiple other registries, but this can involve a significant development effort that ultimately would only support read-only operations. WebSphere Application Server V6.1 provides a new option: a federated user repository. This feature makes it much simpler to use multiple repositories, since this capability is achieved through configuration -- rather than development -- with the use of the new Virtual Member Manager (VMM). In essence, this feature provides the ability to map entries from multiple individual user repositories into a single virtual repository. The federated repository consists of a single named realm, which is a set of independent user repositories. Each repository may be an entire external repository or, in the case of LDAP, a subtree within that repository. The root of each repository is mapped to something called a base entry within the federated repository, which is basically a starting point within the hierarchical namespace of the virtual realm. You will understand this more clearly later when we describe how to configure the VMM. What we are discussing here is the idea of one logical registry containing users from multiple underlying repositories. To the WebSphere Application Server runtime, there is still only one registry, and thus, all applications in the cell still share this one single registry. Refer to Figure 1. Figure 1. Registries seen by WebSphere Application Server Page 2 of 42

3 The Virtual Member Manager is a new component that incorporates some of the existing capabilities in the WebSphere registry, the WebSphere Member Manager (from WebSphere Portal), and a subset of the secure administrations functions. The goals 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 multiple repositories in a federated model. Careful readers might notice that a custom repository is not included in the list of what can make up a federated repository realm. As it exists today, VMM does not support custom repositories. Therefore, if you need a custom repository, you cannot use VMM. Instead, you must write a custom user registry, the same as you needed to do in previous releases. We expect this restriction to be eliminated in the Page 3 of 42

4 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 custom registry options, federated repositories provide user and group management with read 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 Virtual Member Manager by configuring a standalone WebSphere Application Server V6.1 instance to run with a federated repository consisting of file, database, and LDAP repositories. We will progressively add repositories to the federated repository and demonstrate the ability to view the different repositories as a logically unified repository for user and group management. You will also learn how to configure LDAP group membership options. Limitations of federated repositories Only one user repository can be configured to be the target for creating users/groups from the administration console. By default, this is the file repository, but this can be changed, as you will see later. You can use the user and group management wsadmin commands to create users/groups in other repositories, or use native tools for those repositories. The username (for example, LDAP uid) must be unique across the different repositories. For example, users cannot have the same uid in different LDAP directories, even under different org structures. If one or more repository in the federation is down, you will not be able to authenticate (even as an admin), regardless of which repository your particular ID is stored in. The VMM component always checks all Page 4 of 42

5 repositories before letting an authentication to succeed. Although VMM has the capability to support multiple realms, WebSphere Application Server only supports a single realm at this time. This is defined at the cell level and is shared by all applications. Additional limitations are listed in the WebSphere Application Server V6.1 Information Center. Configure a federated repository By default, WebSphere Application Server V6.1 enables administrative security during installation. Unless this option is disabled, the file based repository is used automatically as the user registry. We will begin our exercise by configuring the built-in file-based repository, with the assumption that administrative security was disabled during installation. If the administrative security option was not disabled during installation then you would have provided the admin user name and password during installation, as shown in Figure 2. Figure 2. Enable administrative security Page 5 of 42

6 We will assume this option was disabled during installation so we can show you how to configure federated repositories from scratch. (Under typical circumstances you should NOT disable administrative security during installation.) To work with the security configuration, access the WebSphere Application Server administration console and navigate to Security => Secure administration, applications and infrastructure. For the purpose of this article, we will only configure administrative security. Otherwise, application security should also always be enabled so your applications can leverage WebSphere Application Server security. 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). Page 6 of 42

7 Set up a federated repository using the built-in file-based repository Here, you will configure the federated repository using the default file-based repository, and then enable administrative security. 1. On the Secure administration, applications, and infrastructure dialog, select Federated repositories from the Available realm definitions drop down, and click Configure (Figure 3). Figure 3. Begin Federated repository setup 2. The federated repository consists of a single realm that contains several base entries. A realm within WebSphere Application Server is an instance of a user registry; the realm is the top level logical entry that represents the user registry. In a federated repository configuration, the federated repository instance is the realm. By default, the Realm name is defaultwimfilebasedrealm (Figure 4). This name can be changed to Page 7 of 42

8 any appropriate name for your environment; it does not need to be same as the realm's base entry. Throughout this article, we will leave the realm name as the default, although in practice you will want to change this to something more appropriate. 3. A base entry identifies the root (or starting point) for a set of objects within that realm; within a realm, there can be several base entries. Each base entry is mapped to the root of a directory tree in a given repository. In flat repository, such as a file-based repository, a base entry is the root of all the entries within the repository. In a hierarchical repository, like LDAP, a base entry is mapped to an entry in the directory information tree that identifies the top of a subtree in the DIT. (We will explain more when we look at LDAP repositories.) By default, there is a single base entry corresponding to the file-based repository with the base entry: o=defaultwimfilebasedrealm (Figure 4). This is the identifier for the root of the file-based repository. All users created under this base entry will have a fully qualified name of uid=<uid>, o=defaultwimfilebasedrealm. Since the file-based repository is not hierarchical, all objects within the file repository will be stored under this base entry 4. WebSphere Application Server V6.1 distinguishes between the user identities for administrators who manage the environment, and server identities for authenticating server to server communications. In most cases, server identities are automatically generated and are not stored in a repository. However, if you are adding a Version 5.0.x or 6.0.x node to a Version 6.1 cell, you must ensure that the Version 5.x or Version 6.0.x server identity and password are defined in the repository for this cell. In such a case, you would enter the server user identity and password (Figure 4). Since we are in a single server environment with only one WebSphere Application Server V6.1 node, we will choose the automatically-generated server identity. We will create a user called "wasadmin" to be the administrative user, which will be created and stored in the file based repository. Click OK. Figure 4. Configure realm properties Page 8 of 42

9 5. Enter and confirm the password for the administrative user ID, then OK (Figure 5). Figure 5. Select password for administrative user ID Page 9 of 42

10 6. The basic federated repository configuration is now complete. Next, you can configure WebSphere Application Server to use administrative security. To do so (Figure 6): a. Check Enable administrative security. b. Application security and Java 2 security are both checked by default. To keep this example simplistic, uncheck Java 2 security. c. Make sure that the value of Current realm definition is set to Federated repositories. If you need to change this value, select Federated repositories from the Available realm definitions drop-down list, then select Set as current. This will change the value of Current realm definition. Figure 6. Enable administrative security Page 10 of 42

11 7. Click on Apply, save the changes, and then restart the server. Administrative security is now enabled. The file repository is configured and users and groups can be added to the file repository through the admin 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 encrypted passwords for the user entries. The passwords for a user is encrypted using a one way hash by applying the message digest algorithm specified in the VMM configuration file (wimconfig.xml). The default value for the message digest algorithm is SHA-1. The algorithm can be updated to a different value using the wsadmin command updateidmgrfilerepository. One of the parameters you can use with this command is the messagedigest Algorithm. 8. To use the admin console again, you will need to log into it using the administrative user ID and password that you just configured. 9. You can now view the users in the file repository by navigating to the Users and Groups section of the admin console. Go to the Manage Users pane and search for existing users; search with a wildcard value * to see users in the default file repository (Figure 7). Page 11 of 42

12 Figure 7. Search for users with wildcard value 10. From the admin console, you have the ability to create and remove groups, add and delete users, and modify group memberships for users. You will now add a user called userfileregistry to the registry. To do this, simple select Create and enter the required information. When you are finished, the Search for users screen will show two users (Figure 8). Figure 8. Create a new user As a convention to make the screen shots in this article easier to understand and follow, user names will be configured with the format of user<registryname>registry. This will make it easy to identify the repository in Page 12 of 42

13 which the user is stored. This naming convention is for the purposes of this article only and is not required by WebSphere Application Server V6.1 when using a federated repository. Set up a federated repository using a database repository You will now configure a database repository, in addition to the file-based repository you created in the previous section. In the Virtual Member Manager, a database repository is a database with a specific predefined schema that supports the standard VMM entity types of PersonAccount, Group, and OrgContainer. It is possible to extend the schema with user-defined entity types, but that topic is beyond the scope of this article. There is also extensibility to the schema in that you are able to add additional user attributes to the predefined entities. What is not supported is the ability to use an existing application database that contains user and group information. The database repository also has the ability to support groups that contain users in other repositories, but this is only true for the database repository; file based and LDAP repositories do not have this capability. (See the WebSphere Application Server Information Center for details on how to configure the repositoriesforgroups parameter using the updateidmgrrepository command.) As a precaution, backup the wimconfig.xml file before configuring additional repositories. If it is necessary to rollback changes made during a new repository configuration, you should be able to do this by 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 the admin console; it can be only configured using the command line wsadmin commands. In this section, you will see how to configure the database user repository using an IBM DB2 database. (If desired, any other database supported by WebSphere Application Server can be used instead, and the steps will be similar.) All changes pertaining to the configuration of a new repository are made to the 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 be created by the wsadmin commands. For this configuration we created a database named wimdb. Page 13 of 42

14 2. Configure a DB2 datasource (using the admin console or wsadmin commands) with the JNDI name jdbc/wimdb. This datasource will be used for configuring the federated repository accessing this database. (See Configuring a data source using the administrative console in the Information Center.) If you encounter a problem related to DB2 classes not found in the classpath while running the wsadmin commands to configure the database repository, check to make sure the WebSphere Application Server variable DB2_JDBC_DRIVER_PATH is set correctly. 3. Set up the repository by using this wsadmin command to create the wimdb tables (replace $WAS_HOME with the actual value of the WAS_HOME environment variable): wsadmin>$admintask setupidmgrdbtables {-schemalocation "$WAS_HOME\etc\wim\setup" -dbpropxml "$WAS_HOME \etc\wim\setup\wimdbproperties.xml" -databasetype db2 -dburl jdbc: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 find the 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 -dn entry in the command defines the root for the distinguished names of the objects to be stored in the database repository. This is not necessarily the same as the base entry for the database repository in the federation. User and groups within the database repository will be created under this root distinguished name, which can be whatever you want it to be (o=database.org is an arbitrary value chosen for the purposes of this article). Successful completion of this command will create the tables shown in Figure 9 (as displayed in the DB2 control center). Figure 9. Database tables created Page 14 of 42

15 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 identifier of this repository in the federated repository. (This will be clear when you see it defined in Figure 10.) This command set the datasource name along with the values required to access the database repository using a direct JDBC connection. This is needed, since there are situations in which the runtime might need to access the federated repository when no datasource is available; in such a situation, direct JDBC access will be used. 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 value of the -dn option of the setupidmgrdbtables command. In this case, Page 15 of 42

16 we used the same name for the base entry name in the federated repository (-name), as that in the actual database repository (-nameinrepository). This is not required; the base name in the federated repository can be set to a different name than the actual repository 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 now configured. 9. When you log into the admin console, you will see that the database repository is now part of the federation (Figure 10). Figure 10. Database repository has been added to the federation Page 16 of 42

17 Also, on the Manage repositories panel (Figure 11), the database repository shows up as a defined repository. (Removing a repository from the federation does not delete the repository definition; that is a separate step.) Figure 11. Manage repositories Page 17 of 42

18 10. There are no users in the database repository yet. When new users are created in the admin console, they are also created in the file based repository. However, you need to make a configuration change if you also want 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 in the admin console so that when users are created they also get created in the database repository rather than in the default file-based repository. Navigate to the federated repository configuration panel at Secure administration, applications, and infrastructure => Available Realm Definitions => Configure and select Supported entity types (Figure 12). Figure 12. Supported entity types Page 18 of 42

19 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 database repository base entry (that is, o=database.org). In this example, change it for the PersonAccount which will enable you to add users to the database repository. (We won't show the details, but you would clearly want 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) to o=database.org and Apply. Figure 14. Change base entry value Page 19 of 42

20 13. Save the changes shown in Figure 14 and restart the server for the base entry change to take effect. When new users are added using the admin console, they can be placed in only one repository: whichever repository is the current default as defined by the base entry you set. If you need to add users to other repositories, use the native tools available to you with those products. 14. Now, create a user with user ID of userdatabaseregistry by selecting Users and groups => Manage users => Create, as shown earlier. When done, users from both the file and database repository are displayed (Figure 15). Figure 15. Search for users You have seen how to configure a database repository and make changes such that new users and groups are created in the database repository, instead of the default file-based repository. In the next section, you will see how the federated repository can 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, which so far contains two repositories: the default file-based repository and a database repository. The basic steps for adding an LDAP directory to a federated configuration are: Page 20 of 42

21 1. Add the LDAP directory to the list of repositories available for configuration for the federated repository. 2. Add baseentries rooted at a particular search base within the LDAP directory. Multiple base entries can be added with different search bases for 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 => Secure administration, applications, and infrastructure => Federated repositories => Manage repositories, and select Add. Figure 16. Add LDAP repository Page 21 of 42

22 2. Enter or select the values shown in Figure 16, then select OK and save the configuration. This adds the Active Directory LDAP to the list of federated repositories available for configuration. You will notice that this configuration lets you specify an LDAP failover server. If you wish, you can list multiple LDAP server replicas by IP address or hostname, and the application servers will automatically failover to one of the backup servers if the primary fails. There are additional properties you can configure for the added LDAP; we will look at those later when we discuss customization and configuration of LDAP attributes. 3. Now that the repository has been added to the list of federated repositories, a base entry needs to be configured to point to a subtree (search base) in the LDAP directory. The base entry enables the entries in the LDAP subtree to become part of the federated repository realm. To configure a base entry in the admin console, navigate to Security => Page 22 of 42

23 Secure administration, applications and infrastructure =>Available realm 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 and database repositories (Figure 17). Now you will add an entry from the Active Directory LDAP. Select Add Base entry to Realm. Figure 17. Existing base entries 5. On the following screen (Figure 18), select TestADS for the Repository name, indicating the name of the previously configured Active Directory LDAP. Add the distinguished name of the base entry in the federated repository and the base distinguished name in the Active Directory LDAP directory to specify the search root. The former name defines a logical root entry for this particular repository in the virtual realm, the latter name is the root of the subtree within the LDAP for the set of objects that will become part of the federated repository. What you have actually done here is define a mapping between and LDAP subtree root and a virtual realm root (base) entry, so that all objects from the LDAP under that subtree 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, then the base entry will be mapped to the root ("") of the LDAP server and all the operations will be performed at root. For most LDAP servers this will not work. Thus, you should contact your LDAP administrator to determine the correct root for the directory. Figure 18. Repository reference Page 23 of 42

24 6. When you save this, the base entries shown in Figure 19 will display in the federated repositories. Figure 19. Repositories in this realm The search base specified is dc=testadsserver,dc=local. In this article, we specify only one subtree for the configured Active Directory LDAP. If you want additional subtrees configured, add additional base entries with appropriate subtree roots. Page 24 of 42

25 7. Restart the server. 8. Now, if you go to the Users and Groups area of the console and search for all users, you will see users from the file-based repository, the database repository, and the Active Directory LDAP server. Note the DN of the LDAP users: it's a concatenation of the actual DN of the user in the LDAP 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 federated repository is shown. The unique ID of the user is the user ID plus the base entry to ensure uniqueness across repositories within the federation; however, this does not eliminate the requirement that all user IDs across all 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 the useradsldapregistry, which was created on the ADS server. Similarly, a group search will show groups from all the repositories. Clicking on an individual user gives more information about the user, as well as the groups the user belongs to. For example, Administrator is a user in the Active Directory LDAP; if you click on this user ID, Figure 21 will display. Figure 21. User detail Page 25 of 42

26 If you click on the Groups tab, Figure 22 will display. Figure 22. Group detail Page 26 of 42

27 Add IBM Tivoli Directory Server With Active Directory LDAP added, we will now follow similar steps to add IBM Tivoli Directory Server to the list of directories. 1. Add a new repository through the admin console as before (Figure 23). Figure 23. Add new repository Page 27 of 42

28 As in the case of Active Directory LDAP, all we need is the Primary host name. Additional LDAP properties need to be configured, which will be discussed later. After adding the IBM LDAP, four repositories will display in the available federated repository list (Figure 24). Figure 24. Available federated repositories Page 28 of 42

29 2. As in the case of Active Directory LDAP, to enable entries from the IBM LDAP to be available within the federated repository, at least one base entry pointing to the base of a subtree needs to be configured. To add a base entry in the admin console, navigate to Security =>Secure administration, applications and infrastructure =>Available realm definitions => Federated repositories => Configure, then select Add Base entry to Realm. 3. On the following panel (Figure 25), select ITDSLdap. Add appropriate Distinguished name in the federated repository (o=itdsldap) and corresponding Base entry in the actual LDAP (dc=ibm, dc=com). When finished, Apply the changes. Figure 25. Configure IBM LDAP The entries will be added under dc=ibm,dc=com within the IBM Tivoli Directory Server LDAP as a part of the federated repository under the base entry distinguished name o=itdsldap, as shown in Figure 26. Figure 26. Federated repositories Page 29 of 42

30 4. Restart the server. Now, a search for users will also show users from the IBM LDAP (Figure 27); the user useribmldapregistry was created in IBM Tivoli Directory Server using ITDS admin tools within (cn=users, dc=ibm, dc=com). Figure 27. Search for all users Page 30 of 42

31 As with other directories, notice that the user IBMLDAPRegistry is qualified with the base 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 and without customizing any LDAP attributes. Here, we will look at additional properties that might need to be configured for LDAP when it is added as a part of federated repository. We say "might" because not all LDAP servers are the same. Different implementations use different object classes to specify user and group information, and different ways of defining group membership. It is therefore likely that the default values will not be adequate. Additional properties that are available are described below, with an example of how to perform the additional configuration for the IBM LDAP directory. When you add an LDAP to the federated repository, three links for additional properties display at the bottom of the configuration panel: Performance Performance lets you set properties related to search timeouts and search result limits for configured LDAPs. Performance properties would be configured while tuning the federated repository. (See Increasing the Page 31 of 42

32 performance of the federated repository configuration in the Information Center for more.) LDAP entity types Out-of-the-box, the Virtual Member Manager component defines three entity types that represent object types managed within the federated repository. These provide a way to map object types in different repositories into a common object model in the VMM. These entity types are: Group -- the entity representing group-related objects in the repository; 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; maps to person objects in LDAP. For example, let's look at the entity type and group object configuration for the IBM LDAP. Groups within IBM LDAP are typically stored under object classes "groupofnames" and "groupofuniquenames". The default value for entity type group is objectclass groupofnames. You therefore need to add the ObjectClass groupofuniquenames to ensure that all group objects defined with this objectclass within the LDAP are correctly mapped 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 of groupofnames;groupofuniquenames. Note the entries are separated by a semicolon (Figure 28). Figure 28. Configure Group entity Page 32 of 42

33 c. You can also specify Search bases and a Search filter on this screen. The search bases specified must be subtrees of the base entry 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 LDAP directory. The search filter configuration specifies the LDAP search filter that is used to search this entity type. Using the LDAP search filter syntax, a valid search filter would be: ( (objectclass=groupofnames)(objectclass=groupofuniquenames)). Additional details on mapping LDAP search filters is described below. d. Save the Group entity type configuration with the added Object classes; the configured object classes for the entity type are shown in Figure 29. Figure 29. Configured object classes Group attribute definition For the Virtual Member Manager to understand which groups an object is Page 33 of 42

34 a member of, you need to define the associated membership attribute for the object class. a. The attributes for an ObjectClass are added under Group attribute definition => Member attributes. In the admin console, navigate to Secure administration, applications, and infrastructure => Federated repositories => Manage repositories => ITDSLdap and select Group attribute definition. Figure 30. Group membership b. The Name of group membership attribute (Figure 30) specifies an LDAP attribute indicating the groups to which an entry belongs. This entry depends on the LDAP being used. For IBM LDAP, the value is ibm-allgroups. Other LDAP server types will have their own attribute that needs to be configured here. You can also specify whether nested and dynamic group membership is within the scope of the membership attribute. (This article does not cover details of these concepts.) Since not all LDAPs will have a supported attribute for defining group membership, this attribute is optional. If the LDAP you use does support this attribute, be sure to use it to establish group membership and improve performance. If the group membership attribute is not specified, the LDAP repository can establish membership by searching all groups, but the resulting performance will likely be much slower. c. In addition to the group membership attribute name, you can also specify the scope of the group membership attribute. This value indicates how the Virtual Member Manager can traverse through the LDAP directory to determine group membership. Depending on how the LDAP directory actually manages information stored in this Page 34 of 42

35 attribute, one or more calls may be needed to determine all the groups that the user is a member of. Specifying the scope can improve the performance of such searches. For a given group membership attribute for a given LDAP, it is necessary to know how the given LDAP manages its membership attribute, and what values this attribute will return. For example, for Active Directory LDAP, the scope of the memberof attribute is Direct, that is, only direct parent groups of the user will be returned. To determine the Nested groups of a user, the VMM must first get the direct groups using the memberof attribute, then go through the returned groups one by one and get their direct groups, and so on. This process results in multiple calls to the Active Directory LDAP. To do the same search for IBM Tivoli Directory Server LDAP using ibm-allgroups this elaborate searching is not required, since ITDS maintains all groups, including nested and dynamic group memberships, using that attribute. Therefore, the scope for the attribute should be set to All so that the VMM knows not to make additional unnecessary calls. d. Figure 30 also shows two Additional Properties that provide the ability to define reverse linkage, which is how groups maintain information about their members, for both static and dynamic groups. For a static group, the membership list is maintained on the object itself as a list of members. For dynamic groups, what is actually maintained in the membership attribute is an LDAP search filter. For each member object class that defines a group, such as groupofnames and groupofuniquenames, you can define the corresponding member attribute for group membership. In our scenario, the member attribute for the groupofnames object class is member, which is present by default. You also need to add a uniquemember member attribute corresponding to the groupofuniquenames object class. In the Additional Properties section, select Member Attributes, then New. e. Add uniquemember as a new Member name, and groupofuniquenames for Object class. Leave the scope default value direct. When finished, the member attributes will appear as shown in Figure 31. Figure 31. Member attributes Page 35 of 42

36 You could also have added member attributes for dynamic groups, but that is beyond the scope of this article. However, you can define both static and dynamic searches for the same object class if you have a hybrid group with both static and dynamic members. Mapping LDAP search filters The search filter for an entity type (group, PersonAccount, orgcontainer) specifies the LDAP search filter that is used to search this entity type. The search filter syntax is a subset of the standard LDAP filter. Some sample filter values in VMM are shown below and compared to query strings that could have been used in a standalone WebSphere Application Server user registry configuration (without using a federated repository). 1. If you want to search by user ID within an LDAP subtree and limit your search to Person objects, then the search filter used would be: ((uid = %v)(objectclass=person)). In the VMM, this filter would need to be specified differently, since the VMM does not support replacement parameters such as "%v". In the VMM, the filter to substitute uid with the specified value is applied by the VMM runtime during login to the application server, according to the login properties specified for an LDAP configured in the federated repository. For example, in Figure 16: while adding the Active Directory LDAP, the Login properties field is specified to be "uid". During login, this translates to a search filter "uid=<value>". If it is also necessary to limit the search to Person objects, this would need to be specified in the search filter, in the PersonAccount entity type, as (objectclass=person). For the configured Active Directory, this would be as shown as in Figure 32. Figure 32. Modify search filter Page 36 of 42

37 Here, the filter (uid=%v) gets implicitly mapped in the VMM runtime. This search filter is potentially also re-mapped from VMM properties to the respective LDAP specific properties. This decoupling enables the use of a standard set of properties across a variety of different registries. In this particular example, the second level of mapping occurs within the VMM, where "uid" gets mapped to an LDAP specific attribute, before the search string is submitted to find the user to the actual LDAP. The mapping of VMM properties to LDAP specific attributes is specified in the VMM configuration file wimconfig.xml. The next example is of a specific filter for Active Directory that explains the mapping in more detail. 2. Next, we will look at a search filter specific to Active Directory LDAP and the changes required to configure such a user search filter in the VMM. This example searches for a user account in an Active Directory LDAP by matching the value in either the "samaccountname" or "userprincipalname" attribute. Here, the LDAP search filter would be: ( (samaccountname=%v)(userprincipalname=%v)). Page 37 of 42

38 Mapping this search string in VMM translates into mapping the Active Directory attributes to properties that are recognized within the VMM. LDAP specific attributes are mapped in the VMM to VMM defined properties, such as uid, cn, sn, and so on. This method provides a generic LDAP independent schema definition. To perform this search, you do not actually need to specify a search filter for the LDAP entity type PersonAccount. In fact, as shown in the previous example, replacement expression "%v" is not supported in a search filter in the VMM. All you need to do is make sure that Active Directory user attributes "samaccountname" and "userprincipalname" are mapped to virtual member manager properties, and that these properties are configured in the Login Properties so that the search expression created internally 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 section in the file where the Active Directory LDAP is configured and add the <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 virtual member manager property "cn". As you did above, add the following to the wimconfig.xml file: <config:attributeconfiguration>... Page 38 of 42

39 <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" by specifying the value uid;cn. Now, during login to the application server, if the user ID value is the search filter will search for or Since "uid" is mapped to "userprincipalname" and "cn" is mapped to "samaccountname", the equivalent value of or is the search filter executed against the Active Directory LDAP. 4. For group search filters, "cn" is the VMM property used to map group name. Again, for a search filter such as (&(cn=%v)( (objectclass=groupofnames)(objectclass=groupofuniquename 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 the admin console To create users and groups in the WebSphere Application Server administrative console and have them stored in your LDAP repository instead of the default file-based repository, you need to make configuration changes similar to those you made earlier to add users to the database repository. The base entry for the default parent needs to be changed to that configured for the LDAP repository. For example, 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). Page 39 of 42

40 Figure 33. Modify base entry 3. Save and restart the server. Now, users added through the admin console will 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 the application server starts. It is also required that the user ID be unique across all user repositories that are configured under the same federated repository configuration. When a user logs in, the Virtual Member Manager runtime searches each of the repositories for all of the occurrences of that user. If multiple instances of that user are found in the combined repositories, an error message is displayed. To enable security for J2EE applications, ensure that the application security option in the security configuration section inside the WebSphere Application Server admin console 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 groups to protected resources within the J2EE applications. For an example, try accessing You should be able to login and authenticate to access this sample application as a user from any of the four configured repositories. Acknowledgements The authors would like to thanks Keys Botzum and Ranjan Kumar for all of their assistance in reviewing the paper and making sure that it made sense and was technically accurate. Page 40 of 42

41 Page 41 of 42

42 Resources WebSphere Application Server V6.1 Information Center About the authors Paul Ilechko Paul Ilechko is a Senior Solutions Architect with IBM Software Services for WebSphere. Mr. Ilechko has over 25 years of experience in the IT Industry, including a background in both mainframe and distributed technologies. He has been involved with WebSphere and J2EE technology almost since their inception. His primary goal is to help IBM clients be successful with these products. Mr. Ilechko has a B.Sc. in Mathematics from the University of London. Vikram Desai Vikram Desai is an Architect with IBM Business Partner Technical Enablement. He has worked with several IBM Business Partners to enable them on WebSphere Platform. Previously he has worked as part of development teams for WebSphere Portal, NextWeb, Federated NAS, WebSphere Application Server, Encina++/Encina. Page 42 of 42