IBM Rational Asset Manager Basic Security

How to connect to LDAP directories by using IBM WebSphere Application Server, Version 6.1

This article explains the steps to configure IBM® Rational® Asset Manager to connect to LDAP directories.


Sami Joueidi, Senior Rational Engineer, IBM Japan

Sami Joueidi holds a master's degree in electrical engineering. He is an IBM Certified Architect and serves on the IBM Architecture Board. As part of the IBM Rational team, he focuses on software architecture management.

Bharath Duggirala (, Solutions Architect, IBM India

Bharath Duggirala works as a Solution Architect at SOA Technology Practice, India Software Labs, Bangalore. He blogs actively at developerWorks blogs.

04 March 2008

Also available in Chinese

About IBM Rational Asset Manager

The new software challenges that organizations face today are generated by complex systems, geographically distributed development, and regulatory compliance requirements. More often, these challenges are addressed by a development approach that emphasizes service-oriented architecture (SOA). SOA implementations are producing new types of metadata that require management across the enterprise. IBM Rational Asset Manager addresses this problem.

Rational Asset Manager is an asset management repository that enables organizations to identify, manage, and govern various kinds of non-runtime assets. An asset is a collection of artifacts, such as applications, components, frameworks, templates, patterns, models, services (that may be part of an SOA initiative), requirements, source code, test cases and other kinds of artifacts. An asset

  • It is for a given context.
  • It includes rules for use.
  • It features variability points.

Rational Asset Manager uses the Reusable Asset Specification (RAS) to define, create, modify, and store assets with related artifacts. It also provides asset type-specific search and governance and measures asset reuse.

Managing users and groups in Rational Asset Manager

To understand how to manage users and user groups in Rational Asset Manager, you must understand the concept of a Community. A Community in Rational Asset Manager is a target audience for assets, as well as a central place for asset sharing and collaboration. A Community may produce, use, and manage assets, and it may be aligned at organizational level or defined for a specific or common project or role (for example, Business Analyst).

The Community is the primary element for organizing the repository, because it is a collection of users, roles, and permissions and their assets. Each Community has one user who is designated as the Community Administrator.

At the heart of security is the application container, such as IBM WebSphere Application Server or Tomcat, which controls security in unison with application-level security within Rational Asset Manager. Users are managed either from file-based user and group security files or populated from a Lightweight Directory Access Protocol (LDAP) directory. Rational Asset Manager can integrate with LDAP to retrieve and reuse existing user and group information and to authenticate users; authorizations for access.

A user group is a list of users that can also be populated by manually adding users or by retrieving user data bound to an LDAP query.

User groups map roles to groups of users for a given Community. Each role has identified permissions. Some default roles are added to a Community, such as Asset Consumer. The users in a user group have the same roles and permissions for a particular Community. Users can also be assigned individual roles within a Community, outside of user groups, and can have multiple roles.

Major steps in configuring Rational Asset Manager v7.0 to use LDAP

To successfully connect Rational Asset Manager to your corporate LDAP system, you need to follow these four steps, in this order:

  1. Set up a file-based User Registry in WebSphere Application Server.
  2. Configure a Rational Asset Manager Custom User Registry to use LDAP.
  3. Set up standalone LDAP integration within WebSphere Application Server.
  4. Add LDAP users and groups to Communities.

Step 1. Set up a file-based user registry in WebSphere Application Server v6.1

Rational Asset Manager relies on the IBM WebSphere Application Server to integrate with the LDAP registry and to authenticate user logins. However, when it is first installed, Rational Asset Manager uses file-based security for user authentication. Therefore, you must configure the application server for file-based security until you have completed the installation and configuration of Rational Asset Manager.

If you install Rational Asset Manager on eWAS (the Web-based version of WebSphere Application Server), the Installation Manager automatically configures this step for you. However, if you install Rational Asset Manager on an existing WebSphere Application Server, then you must configure file-based security yourself.

If you install Rational Asset Manager on an existing WebSphere Application Server that is already configured for LDAP (or other security), you must reconfigure that server for file-based security until you have completed the installation and configuration of Rational Asset Manager. After installing and configuring WebSphere Application Server to use a custom user registry, you can restore the previous security configuration. See the Troubleshooting section of this article for instructions.

The following subsections provide instructions for configuring file-based security on WebSphere Application Server Version 6.1.

Copy the users and groups properties files to WebSphere Application Server

Before starting the file-based security setup process, you need to copy the user.props and groups.props text files to the Rational Asset Manager profile for your WebSphere Application Server. You can find these in the directory where Rational Asset Manager is installed, for instance:

C:\Program Files\IBM\SDP70\ram\conf\security

Rational Asset Manager v7.0 does not provide a Web or a GUI interface to add users and groups. Instead, the users and groups are created and added to the properties (.props) files. If you add users or groups, do so in the properties files, and then restart WebSphere Application Server.

The entries in the users.props file follow this format:

name:passwd:uid:gids:display name

  • name = user ID of the user
  • passwd = password of the user
  • uid = unique ID of the user
  • guid = group IDs of the groups that the user belongs to
  • display name = (optional) display name for the user

To copy the user.props and groups.props text files:

  1. Create a new security folder in the <WAS Base>\profiles\AppSrv01\properties folder.
  2. Copy the user.props and groups.props text files:
    1. From (where C = your drive):
      C:\Program Files\IBM\SDP70\ram\conf\security
    2. To (where WAS Base = WebSphere Application Server location):
      <WAS Base>\profiles\AppSrv01\properties\security

Configure WebSphere Application Server 6.1 for file-based security

  1. Start the WebSphere Application Server for Rational Asset Manager if it is not already running. You can run the server from a command line, for example:
    "<WAS Base>\profiles\AppSrv01\bin\startServer.bat" server1
  2. Launch the WebSphere administrative console by opening the browser and entering this (where port is the configured port number to access the WebSphere Application Server console):
  3. Click Log in without a User ID.
  4. In the left panel, click Security > Secure administration > application > infrastructure.
  5. Under the User account repository, select Standalone custom registry, and then click Configure.
  6. Click Security.
  7. Click Secure administration > applications > infrastructure.
  8. Under Available realm definitions, select Standalone custom registry, and then click Configure.
  9. Click Custom Properties.
  10. Click New.
  11. In the Name field, type groupsFile.
  12. In the Value field, type the path to the groups.props file, for example:
    <WAS Base>\profiles\AppSrv01\properties\security\groups.props
  13. Click Apply, and then click OK.
  14. Click New.
  15. In the Name field, type usersFile.
  16. In the Value field, type the location of the users.props file, for example:
    <WAS Base>\profiles\AppSrv01\properties\security\users.props
  17. Click Apply.
  18. Click Standalone custom registry at the top of the page.
  19. Click Save. (See Figure 1.)
Figure 1. Where to save your changes
Save your changes

The Custom Properties should look something like Figure 2.

Figure 2. Custom Properties
  1. In the Primary administrative user name, Server user ID, and Password fields, type admin.
  2. Click OK.
  3. On the Configuration page:
    1. Select Enable administrative security.
    2. Uncheck Use Java™ 2 security.
    3. Ensure that Enable application security remains checked.
    4. Ensure that Available realm definitions is set to Standalone custom registry.
    5. Click Set as current.
    6. Click Apply.
    7. Click Save (see Figure 3)
Figure 3. Where to save your changes
Save your images
  1. Log out of the administrative console.
  2. Restart the application server for Rational Asset Manager.

Step 2. Configure the Rational Asset Manager v7.0 custom user registry to use LDAP

Rational Asset Manager can integrate with LDAP repositories to perform user authentication, retrieve user information, and leverage group bindings. It is preconfigured to work with a generic LDAPUserInformationFactory that is designed to work with an LDAP v3 registry. However, if the default is not desirable, you can configure Rational Asset Manager to use a custom user class, instead, by customizing it to extend the generic UserInformationFactory class.


  • You must designate an administrator user for Rational Asset Manager and a valid user in LDAP before setting up Rational Asset Manager and the WebSphere Application Server container to use LDAP. You will provide the user ID when you follow the configuration steps after this.
  • If you enable LDAP integration within the WebSphere Application Server administrative console before configuring Rational Asset Manager for LDAP integration (within Rational Asset Manager), you will not be able to log in to Rational Asset Manager.
  • The LDAP connection is configured at the Rational Asset Manager repository level, not at a Community level. When an LDAP connection is configured, each Community can query LDAP for specific users.

Before configuring and enabling LDAP integration in the WebSphere Application Server administrative console, you must first configure the Rational Asset Manager Custom User Registry for LDAP integration.

To set up Rational Asset Manager to integrate with LDAP, follow these steps.

  1. Log in to the Rational Asset Manager Web application as an administrator (default: admin).
  2. Click the Administration tab.
  3. Under Repository Administration, click the Configuration link (see Figure 4).
Figure 4. Repository Administration screen
Repository screen
  1. In the Custom User Registry section, check Use a Custom User Registry.
  2. Use the default class:
  3. Enter the LDAP login ID in the Administrator ID field. This is the user who will have administrator permission to access Rational Asset Manager (the ID will no longer be admin). This user must be already defined in the LDAP registry. For example: ramadmin (see Figure 5).
Figure 5. Custom User Registry entries
User Registry entries
  1. Next, click Configure.
  2. Fill in the LDAP information on the Custom User Class Configuration page. Enter a space if you want a value to be null. Otherwise, leave a field blank for it to revert to its default value (definitions of the fields follow).
  3. Click Update Configuration.
  4. Click Save at the bottom of the Configuration page.

Here are the definitions of each of the fields:

  • LDAP server's URL. The URL to the LDAP server; It must start with ldap:// or ldaps:// for a secured connection. For example: ldap://
  • User's Distinguished Name. The name of the user who can log in and access the LDAP registry. This needs to be a user who has complete LDAP search access to the User and Group database searching as defined here. For example:
  • User's Password. The password for the User's Distinguished Name, as defined previously.
  • User's Unique ID property. The property name of the user's objectClass instance that represents the unique user's ID, such as a login name or an e-mail address. For example: uid or mail
  • User's Login ID property. The (objectClass) property that the person uses to log in. The User's Unique ID and User's Login ID property are often the same. For example: uid
  • User's Phone Number property. The (objectClass) property that represents the user's telephone number from LDAP. For example: telephonenumber
  • User' e-mail property. The property of the (objectClass) that represents the user's e-mail address, which is typically mail.
  • LDAP User base searching. You can enter the value of the path of the root from where to start the search to avoid searching parts of the LDAP registry that do not contain user objects. For example: dc=abcglobal,dc=com
  • User search filter. The template to use when searching for a user. The %v represents the search term that was entered from an input text field. The search will run as if a wild card is appended to the search term. The default search template is constructed to find all person objectClasses where either the mail property or the name property is the same as the search term. For example: (uid=%v)
  • LDAP Group base search. The base search for searching groups. It is similar to a user's base search, as described previously. For example: dc=abcglobal,dc=com
  • Group search filter. A filter for searching groups. The default searches any of groupOfUniqueNames (static group), groupOfNames (static LDAP group), groupOfUrls (dynamic LDAP group), and group (Active Directory-defined group) for the search term entered by the user. For example: (&(cn=%v)(objectclass=groupOfUniqueNames))
  • Image URL template. This is to retrieve a user's image by using the URL where the user's image resides (stored somewhere other than the LDAP registry). For example, you can use the default:
    https://<ImageServer url>/photo/${uid}.jpg

Figure 6 shows a screen capture with completed information.

Figure 6. Completed configuration entries
screen capture with completed configuration entries

Step 3. Set up standalone LDAP integration within WebSphere Application Server

Now that you have configured Rational Asset Manager to integrate with LDAP, it is time to set up the LDAP integration within WebSphere Application Server.

To use LDAP v3 as the user registry, you must have a valid user name (ID), the user password, the server host and port, the base DN and, if necessary, the bind DN and the bind password.

Set up the security administration

Follow these steps to set up WebSphere Application Server security for the standalone LDAP registry:

  1. Launch the WebSphere Application Server administrative console for the Rational Asset Manager instance.
  2. Click Security > Security administration > application > infrastructure in the administrative console.
  3. In the User Account repository, under Available realm definitions, select Standalone LDAP registry.
  4. Click Configure (see Figure 7).
Figure 7. User Account Repository configuration
Repository configuration
  1. In the Primary administrative user name field, enter a valid user name. You can enter either the complete Distinguished Name (DN) of the user or the short name of the user, as defined by the user filter in the Advanced LDAP settings panels. This ID is the security server ID, which is used only for WebSphere Application Server security and is not associated with the system process that runs the server. For example: ramadmin
  2. From the Type of LDAP server list, select the type of LDAP server to use. The type of LDAP server determines the default filters that WebSphere Application Server uses. These default filters change the Type field to Custom, which indicates that custom filters are used. This action occurs after you click OK or Apply in the Advanced LDAP settings panel.
  3. From the list, select the Custom type, and modify the user and group filters to use other LDAP servers, if required. In this example, select IBM Secureway Directory Server.
  4. In the Host field, enter the fully qualified host name of the LDAP server. You can enter either the Internet Protocol (IP) address or Domain Name Server (DNS) name. For example:
  5. In the Port field, enter the LDAP server port number. The host name and port number represent the realm for this LDAP server in the WebSphere Application Server cell. Therefore, if servers in different cells are communicating with each other by using Lightweight Third Party Authentication (LTPA) tokens, these realms must match exactly in all the cells. For example: 10345
  6. In the Base Distinguished Name field, enter the base DN. The base DN indicates the starting point for searches in this LDAP directory server. You must ensure that the Ignore Case option is always enabled. Ignore Case is required, and disabling it might cause authorization errors because of case sensitivity. This field is required for all LDAP directories except the IBM Lotus® Domino® directory. The Base Distinguished Name field is optional for the Domino server. For example:
  7. In the Bind Distinguished Name field, enter the bind DN name. The bind DN is required if anonymous binds are not possible on the LDAP server to get user and group information. If the LDAP server is set up to use anonymous binds, leave this field blank. If a name is not specified, the application server binds anonymously. For example:
  8. In the Bind password field, enter the password that corresponds to the bind DN.
  9. Optional: Modify the Search timeout value. This timeout value is the maximum amount of time that the client that sends a search request can wait for a response before timing out.

Figure 8 shows the entries so far.

Figure 8. Completed entries
Completed entries
  1. Ensure that the Reuse connection option is selected. This option specifies that the server must reuse the LDAP connection. Clear this option only in rare situations where a router is used to send requests to multiple LDAP servers and when the router does not support affinity. Leave this option selected for all other situations. (See Figure 9.)
  2. Verify that the Ignore case for authorization option is enabled. When you enable this option, it means that Java™ 2 Platform, Enterprise Edition (J2EE) authorization is case insensitive. Typically, an authorization check involves checking the complete DN of a user, which is unique in the LDAP server and is case sensitive. However, when you use either the IBM Directory or the Sun® ONE™ Directory LDAP server, you must enable this option, because the group information that is obtained from LDAP servers is not consistent in case. This inconsistency affects only the authorization check. Otherwise, this field is optional and can be enabled when case sensitive authorization check is required. You can also enable the "Ignore case for authorization" option when you are using SSO (single sign-on) between the product and Lotus Domino. The default is Enabled.
  3. Optional: Select the Secure Sockets Layer (SSL) enabled option if you want to use Secure Sockets Layer communication with the LDAP server. If you select the SSL enabled option, you can select either the centrally managed or the "Use-specific SSL alias" option.
Figure 9. Default and optional settings
Default and optional settings
  1. Click the Save link (Figure 10), and then click Save directly to the master configuration.
Figure 10. Save directly to the master configuration
Saving to master configuration

Set up the Advanced LDAP user registry configuration

Now it is time to complete the steps to configure the advanced LDAP user registry settings:

  1. Click Security > Secure administration > applications > infrastructure (if not already there).
  2. Under User account repository, select Standalone LDAP registry, and click Configure.
  3. Under Additional properties, click Advanced Lightweight Directory Access Protocol (LDAP) user registry settings.

You will notice that default values are already populated for all of the user- and group-related filters, based on the type of LDAP server that is selected in the "Standalone LDAP registry setting" panel. When security is enabled and any of these properties change, go to the Secure administration, applications, and infrastructure panel shown in Figure 11.

Figure 11. Secure administration, applications, and infrastructure panel
Secure administration panel
  1. Click Apply or OK to validate the changes.
  2. Click the Save link (see Figure 12), and then click the Save button.
Figure 12. Save your changes
Saving changes
  1. Click the Logout link at the top to leave the WebSphere Application Server administration console.
  2. Restart WebSphere Application Server.

See the table that follows for the Property default values and descriptions.

Property default valueDescription
User filter: (&(uid=%v)(objectclass=ePerson))Specifies the LDAP user filter used to search the registry for users.
Group filter: (&(cn=%v)(|(objectclass=groupOfNames)(objectclass=groupOfUniqueNames)))Specifies the LDAP group filter used to search the registry for groups.
User ID map: *:uid Specifies the LDAP filter that maps the short name of a user to an LDAP entry. This field takes multiple objectclass:property pairs delimited by a semicolon (;).
Group ID map: *:cnSpecifies the LDAP filter that maps the short name of a group to an LDAP entry. This field takes multiple objectclass:property pairs delimited by a semicolon ;.
Group member ID map: ibm-allGroups:member;ibm-allGroups:uniqueMemberSpecifies the LDAP filter that identifies user to group relationships.
Perform nested group search: uncheckedSelect this option if the LDAP server does not support recursive server-side group member searches.
Certificate map mode: EXACT_DNSpecifies whether to map X.509 certificates into an LDAP directory by EXACT_DN or CERTIFICATE_FILTER. Specify CERTIFICATE_FILTER to use the specified certificate filter for the mapping.
Certificate filter: (&(uid=${UniqueKey}))The filter is used to map attributes in the client certificate to entries in the LDAP registry. The syntax or structure of this filter is:
LDAP attribute=${Client certificate attribute}
For example: uid=${SubjectCN}

After LDAP integration is enabled within the WebSphere Application Server administrative console, you cannot log in by using "admin" as the user ID and password. You must restart the server after making any changes to the Custom User Registry settings.

Test the configuration

Next, ensure that your WebSphere Application Server and Rational Asset Manager configurations are working properly.

  1. Launch the WebSphere Application Server administrative console in a Web browser.
  2. This time, log in by using the Primary administrative user name (Server user ID) that you entered previously in the WebSphere Application Server configuration section.
  3. Click Log in.
  4. If WebSphere Application Server is configured correctly, you will see the Welcome screen.
  5. Click the Logout link to log out.

Now try Rational Asset Manager:

  1. Launch Rational Asset Manager.
  2. Sign in by using the Administrator ID that you configured in the Rational Asset Manager configuration steps previously.
  3. If the configuration is working, you should be able to log in.


WebSphere Application Server may not start if it is unable to connect to the LDAP server. Therefore, you will not be able to access the administrative console. You will need to manually edit the security.xml file by following these steps:

  1. Navigate to your WebSphere Application Server profile:
    <WAS Base>\profiles\AppSrv01\bin\/${wasBaseDir}/profiles/default/config/cells/${nodeName}Node01Cell/
    For example:
  2. Edit the security.xml file as the Code Listing that follows shows.
    1. If you previously had security enabled and had a custom user registry, change the text (in bold) to activeUserRegistry="CustomUserRegistry_1".
    2. Otherwise, if you did not previously have security enabled, change the text (in bold) to enabled="false".
Code Listing. Edit the security.xml file
enabled="true" cacheTimeout="600"
  1. Save the file.
  2. Restart WebSphere Application Server.
  3. Launch the administrative console in a Web browser. This time, do not use the LDAP user ID to log in.
  4. Click Log in.
  5. Fix the problem with your configuration, and restart WebSphere Application Server.

Step 4. Add LDAP users and user groups to Rational Asset Manager communities

You are almost finished. So far, you have completed the necessary steps to properly configure Rational Asset Manager to use LDAP for user authentication and user information retrieval. Community administrators can now complete the remaining asks:

  1. Add users
  2. Bind User Groups to Groups in LDAP
  3. Configure and assign permissions


We would like to thank Chris Busch for his technical input. Chris is a Business Flexibility (SOA) Practice Lead with the IBM Rational TechWorks team in the United States. He is the co-author of the IBM® Redbook® titled, "Strategic Reuse with Asset-Based Development."



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Rational software on developerWorks

ArticleTitle=IBM Rational Asset Manager Basic Security