Tip: Advanced configuration of WebSphere with Federated Realm


This article expands upon the use of WebSphere Application Server(WAS) with a Federated Registries for advanced configurations where there are multiple LDAP directories, or you need to use a combination of LDAP directories and file based user repositories.

More Information

The first two articles on this topic Configuring WAS with Federated realm and Configuring WAS with LDAP realm covered the manual creation of user and groups to create a setup analagous to the use of Apache Tomcat using the tomcat-users.xml file to manage users and role access and how to setup WAS for an LDAP configuration for use with a single corporate wide directory. This article focuses on some other common scenarios using the WAS Federated registries technology that combines multiple user repository types into a single federated user repository available to the applications using container managed security. Figure 1 shows the different authentication options supported through WAS.

WebSphere Application Server Authentication Architecture
Figure 1: WebSphere Application Server Authentication Architecture.1

As you can see there are many possible combinations, this article will only cover a few common file and directory variants, but the general procedure and some basic limitations will be the similar regardless of the type or user registry you use. For some useful background information on how Jazz Authentication is done, review the article Jazz Team Server Authentication Explained for a details discussion on this topic. The key understanding that you need is to differentiate between the user roles in Jazz and user authentication and authorization roles that are handled by the application server.

Jazz Container Managed Security
Figure 2: Jazz Container Managed Security.2


For each of these configurations, we will assume that you have configured your LDAP server(s) and imported any required SSL certificates. Additionally the instructions below are written for IBM Websphere Application Server(WAS) 7.0 specifically so there will be some minor differences to apply this to a 6.x environment. By default a clean install of WAS is setup using Federated Repositories as the default security realm and during install time you are given the option to enable Administrative Security. Once installed you should have the WAS username and password or if you did not enable security we will not need this. Also note that when performing these steps in a production environment you will need to stop and start the WAS profile to configure and enable new security settings, so plan accordingly.

In order to complete these steps you will need to have pre-configured users in your directory server(s) and information about connecting to your LDAP directory server(s), the WebSphere administrator password, and finally a working Jazz environment to validate your configuration with. It is also recommended that you ensure that you Jazz server is configured in WebSphere Application Server and working. Here we will focus on the following three common scenarios, since the technical details of performing these tasks is already provided by WebSphere I will provide references to the detailed instructions and keep the discussion here at a high level and relevant to the use with Jazz.

  1. Hybrid LDAP & File Based Realm
  2. Combining Multiple LDAP Servers
  3. Single LDAP custom server mapping of groups and users to roles

Generic Procedure for configuring WAS global security

More detailed and up to date instructions can be found in the WAS online documentation: Managing the realm in a federated repository configuration. Below the high level procedure is briefly repeated for clarity.

  1. Configure your Federated Repositories or Standalone LDAP Registries realm to connect to your various user registry sources.
  2. Configure supported entity types.
  3. [Optional] Setup property mapping and property extensions.
  4. [Optional] Update the settings for the LDAP repositories in your realm. (Performance, Entity Types, Group Attribute)
  5. Add the External Repository to the Federated Repositories Configuration.
  6. Ensure that the correct realm(Federated repositories/Standalone LDAP Registry) is identified in the Current realm definition field.
  7. Once the changes are saved to the master configurations, then restart all effected servers (deployment managers, nodes, and Application Servers).
  8. Perform the Role mappings at the application level.

Hybrid LDAP & File Based Realm

A common requirement for teams that may have service or special users that may not contained in the corporate directory. One example of this configuration is to use both the File Based Registry and an LDAP directory together. This is useful where it may not be possible or feasible to create certain service user accounts in the corporate directory for each specific teams, consider the number accounts required for access via integrations or accounts for managing automations.

The built-in File Based Registry will be used to store and authenticate our service accounts and LDAP for standard user account authentication from the corporate directory, authorization will be handled based on our group mapping in the Jazz applicaiton.

  1. Add desired service accounts to WAS in Users and Groups: Manage Users.
  2. Add our LDAP directory to the Security: Federated Repositories: Security > Global Security, click Manage Repositories and add the LDAP directory or directories.
  3. Navigate to Security: Global Security > Federated Repositories and click Add Base Entry to Realm. Provide a meaningful name for the base, as well as the search base that will provide access to both the user and group DNs we provided earlier.
  4. Restart WAS
  5. Verify our user/group mappings(Tip #3 below), we should see both the LDAP users/groups and users/groups added to the File Based repository.
  6. Now we are ready to use both the users and groups in the Jazz application in the application’s Security role to user/group mapping configuration.


  • Only possible import in batch from the LDAP server, all users from File Registry must be created manually in your Jazz Repository.
  • Managing the Jazz Role mappings must be done via WAS.

Combining Multiple LDAP Servers

This scenario is useful if your organization needs to work across multiple LDAP directories, for instance multiple Windows Active Directory Domains that are not in the same forest or an organization that maintains directories across business/organizational units. To accomplish this use the WAS Federated Repositories, here we will may or may not have a file based realm to store WAS administrative users, this is a matter of preference and internal security guidelines for the scenario below we assume that it is removed and administration is done by users of the directories once security is enabled. While configuring a system where the file based registry is removed it is required to configure the primary administrative user from one of our LDAP servers. The process is the same for each respository added where only the directory information will change so we will just cover adding to similar directories and the process can be repeated for configurations requiring more.

  1. Navigate to Security: Global Security > Federated repository > Manage Repositories for each LDAP server that will be used in this configuration.
  2. Now that each respository connection has been created, we need to add them to the Federated Repository. Add each user respository to the Federated Realm.
  3. [Optional] Remove the default file based realm.
  4. [Optional] Update the primary administrative from the default file based version, to a user from your newly added directories.
  5. Save your changes to the master configuration and restart WAS to put the new security settings into effect.
  6. Login to the console, as the primary adminstrative user (If you hit problems or can no longer login, we can disable security and try again see Tip #1 below).
  7. Verify our user/group mappings(Tip #3 below), we should be able to query for both users and groups from either domain.
  8. Now we are ready to use both the users and groups in the Jazz application in the application’s Security role to user/group mapping configuration.


  • Cannot have the same user id in more than one repository.
  • Can only import/sync users from currently configured LDAP directory, requires update of config to change, can be done on a running system but currently a manual process.
  • WebSphere Applications requiring authentications will not be accessible if any one of the LDAP servers is unavailable, so if that is a concern multiple repositories introduces multiple points of failure into your WebSphere authentication infrastructure.
  • Mapping LDAP directories with different LDAP schemas may require that we map different attributes and may require additional configuration on the WAS side to perform the mapping.

Single LDAP custom server mapping of groups and users to roles

In some cases it is not possible to do a single grouping of all required users into a single consolidated group, while it is possible to maintain this mapping in the applications web.xml file as you do to accomplish this from Tomcat, it may also be useful to have a unified view of roles mappings inside of WebSphere. In this scenario it is possible to create and maintain the many-to-one mapping inside of WebSphere and leave the configuration details of your Jazz products to use the default roles. Coverage of the corresponding configuration for Tomcat is described in the article Configuring Tomcat with LDAPLocalGroup Realm.

This configuration is maintained directly in the application’s security configuration in WAS Applications: Application Types > WebSphere Enterprise Applications and click Security role to user/group mapping. The benefits here is that if you choose you can continue to also use the LDAP mappings for the majority of your users and use this method for the edge cases. Also updating these custom group membership requires access to the WAS console, but they can also be done on the fly and do not require a restart.

Figure 3: Application level Role mapping with LDAP group mappings as well as individual user mappings.


  • The Jazz Role mappings must be managed manually or using WAS tools in addition to the mappings from LDAP.

Troubleshooting Tips:

Along the way you may run into some common problems when configuring WebSphere Application Server, here a tips I have found helpful.

  1. Reseting User Security if you lock your self out

    If you find that you cannot login after restarting your WAS instance, it is pretty easy to disable security and try again we just need access to the system it is hosted on. One method is to use wsadmin scripting to disable security, below is an example on linux using JACL.

      	$ cd $WAS_PROFILE_HOME  	$ ./bin/wsadmin.sh -lang jacl -conntype NONE  	WASX7357I: By request, this scripting client is not connected to any server process. Certain configuration and application operations will be available in local mode.   	WASX7029I: For help, enter: "$Help help"  	wsadmin>securityoff  	LOCAL OS security is off now but you need to restart server1 to make it affected.  	wsadmin>quit  	$  	  

    Once security is off, you will need to restart WAS as noted in wsadmin, however if security is not working properly the normal shutdown process is not working and you will need to kill the WAS processes at the operating system level.

  2. Validating your group memberships

    A useful troubleshooting tip if the application is not behaving as expected we can use the /<context_root>/authenticated/identity service to return the current users roles. This service returns a JSON document with the current authenticated users id and roles. For example, here is user that is a member all the roles.

      {  	"userId": "watson@us.ibm.com",  	"roles": [  		"JazzGuests",  		"JazzDWAdmins",  		"JazzUsers",  		"JazzProjectAdmins",  		"JazzAdmins"]  }	     	   
  3. Verifying that your user/group mappings are working as expected.

    After completing the security realm configuration, we can verify that our settings are correct by attempting to find our users, groups, and memberships across all configured registriesby using the Users and Groups: Manage Users/Manage Groups to do some querying for known users and groups, as well as verifying that user results show the correct group memberships. When viewing the results you can also validate that the group memberships look correct by viewing a particular user.

    Figure 4: View from Manage Users showing results from multiple LDAP registries.
Was this information helpful? Yes No 10 people rated this as helpful.